Executable specs that survive rewrites.
\n\n\n Documentation ·\n 한국어 문서 ·\n GitHub\n
\n\nBelay is a black-box scenario harness. Your project goes in `src/`. Your specs go in `test/`\nas Gherkin scenarios backed by TypeScript step definitions. One command boots the mock\ninfrastructure, starts your app, waits until it is genuinely ready, runs every scenario,\ncollects evidence, and tears everything down.\n\nThe specs never import your code. They only knock on the surfaces a user can reach — HTTP,\nGraphQL, WebSocket, gRPC, CLI, the browser. That single constraint is what makes them survive\na rewrite.\n\n## Install\n\n```bash\nnpm install -g @beoks/belay\nbelay init\nbelay run\n```\n\nOr per project:\n\n```bash\nnpm install -D @beoks/belay\nnpx belay init\n```\n\nRequires Node ≥ 22. Zero runtime dependencies.\n\n## Writing a step\n\n```ts\nimport { Given, Then, expect, World } from '@beoks/belay';\n\nGiven('the audit system answers {int}', function (this: World, status: number) {\n this.mock.audit.onPost('/events').reply(status); // the stub is ours; program it freely\n});\n\nThen('the status is {int}', function (this: World, status: number) {\n expect(this.last.status).toBe(status);\n});\n```\n\n## Commands\n\n```bash\nbelay init # scaffold config + test skeleton (interactive)\nbelay init --from ../my-api # adopt an existing project (--link symlink|submodule|move|copy)\nbelay analyze # inventory existing code into a scenario checklist\nbelay run # boot → run → collect → tear down\nbelay run --only L1 # one layer (--upto L2 also works)\nbelay run --grep signup # filter by name (--tags \"@smoke\" too)\nbelay run --bail # stop at first failure\nbelay run --watch # re-run on change; the environment stays up\nbelay new L1-account/signup # create a .feature and its steps together\nbelay approve cart-empty # accept a visual baseline, after reviewing the diff\nbelay report --open # open the latest HTML report\nbelay doctor # check ports, Docker, engines, config\nbelay down # clean up a kept environment\n```\n\n## Optional peers\n\nThe browser driver and visual gate need optional peers, installed only if you use them:\n\n```bash\nnpm i -D playwright pngjs pixelmatch && npx playwright install chromium\n```\n\nThe gRPC driver needs `@grpc/grpc-js` and `@grpc/proto-loader`.\n\n## Language\n\nScaffolding and Gherkin are English by default; set `BELAY_LANG=ko` for Korean.\n\n```bash\nbelay init # English scaffolding and Gherkin\nBELAY_LANG=ko belay init # Korean scaffolding and Gherkin\n```\n\nThe [full design document](https://beoks.github.io/Belay/) covers the layer model, the driver\nsurfaces, the mock infrastructure and the agent workflow.\n\nMIT © BEOKS\n","readmeFilename":"README.md"}