Belay is a black-box scenario harness. Your project goes in src/. Your specs go in test/ as Gherkin scenarios backed by TypeScript step definitions. One command boots the mock infrastructure, starts your app, waits until it is genuinely ready, runs every scenario, collects evidence, and tears everything down.

The specs never import your code. They only knock on the surfaces a user can reach — HTTP, GraphQL, WebSocket, gRPC, CLI, the browser. That single constraint is what makes them survive a rewrite.

Install

npm install -g @beoks/belay
belay init
belay run

Or per project:

npm install -D @beoks/belay
npx belay init

Requires Node ≥ 22. Zero runtime dependencies.

Writing a step

import { Given, Then, expect, World } from '@beoks/belay';

Given('the audit system answers {int}', function (this: World, status: number) {
  this.mock.audit.onPost('/events').reply(status);   // the stub is ours; program it freely
});

Then('the status is {int}', function (this: World, status: number) {
  expect(this.last.status).toBe(status);
});

Commands

belay init                    # scaffold config + test skeleton (interactive)
belay init --from ../my-api   # adopt an existing project (--link symlink|submodule|move|copy)
belay analyze                 # inventory existing code into a scenario checklist
belay run                     # boot → run → collect → tear down
belay run --only L1           # one layer          (--upto L2 also works)
belay run --grep signup       # filter by name     (--tags "@smoke" too)
belay run --bail              # stop at first failure
belay run --watch             # re-run on change; the environment stays up
belay new L1-account/signup   # create a .feature and its steps together
belay approve cart-empty      # accept a visual baseline, after reviewing the diff
belay report --open           # open the latest HTML report
belay doctor                  # check ports, Docker, engines, config
belay down                    # clean up a kept environment

Optional peers

The browser driver and visual gate need optional peers, installed only if you use them:

npm i -D playwright pngjs pixelmatch && npx playwright install chromium

The gRPC driver needs @grpc/grpc-js and @grpc/proto-loader.

Language

Scaffolding and Gherkin are English by default; set BELAY_LANG=ko for Korean.

belay init                # English scaffolding and Gherkin
BELAY_LANG=ko belay init  # Korean scaffolding and Gherkin

The full design document covers the layer model, the driver surfaces, the mock infrastructure and the agent workflow.

MIT © BEOKS