01 설치와 시작

전역 설치 한 번, belay init 한 번. 그다음부터는 belay run만 반복합니다.

Belay는 전역 CLI로 설치합니다. 검증 대상인 src/가 어떤 언어로 쓰였든 상관없기 때문에, 하네스와 대상의 런타임은 서로 섞이지 않습니다. Node는 Belay를 돌리기 위한 것이지 프로젝트의 제약이 아닙니다.

요구 사항

설치

npm install -g @beoks/belay

belay --version
belay doctor        # 포트·Docker·엔진 상태를 미리 점검

초기화

빈 디렉터리에서 시작하든 이미 굴러가는 프로젝트에서 시작하든 명령은 같습니다. init은 현재 디렉터리를 살펴 감지한 것을 기본값으로 제안합니다.

mkdir my-project && cd my-project
belay init

  # 엔터를 누르면 대괄호 안의 기본값이 쓰입니다.
  # 감지됨: npm --prefix src start

  검증할 표면 (쉼표로 구분: http, graphql, ws, browser, cli)
  [http] > http, ws

  src 를 실행하는 명령
  [npm --prefix src start] >

  준비 완료를 판정할 URL
  [http://localhost:8080/health] >

  외부 API 스텁을 만들까요? (Docker 불필요, 인메모리)
  [y/N] > y

  메일 캡처 서버를 만들까요? (SMTP)
  [y/N] > y

  ✓ src/                   # 없으면 만들어 둡니다 — 검증 대상이 사는 곳
  ✓ belay.config.ts        # 선택한 표면과 인프라가 채워진 상태로
  ✓ test/support/world.ts
  ✓ test/support/steps/common.steps.ts
  ✓ test/features/L0-smoke/health.feature   # 첫 확보 지점
  ✓ test/features/L0-smoke/health.steps.ts
  ✓ AGENTS.md              # 에이전트가 test/ 를 고치지 못하게 하는 규칙
  ✓ .github/workflows/belay.yml
  ✓ .gitignore
  ✓ package.json           # test · test:smoke · test:watch 스크립트

  다음 단계
    1. src/ 에 검증할 프로젝트를 두고 belay.config.ts 의 app.start 를 확인하세요
    2. belay run --only L0   # 첫 확보 지점을 통과시키세요
    3. belay new L1-<도메인>/<기능>   # 스펙을 시나리오로 고정하세요

생성되는 것

my-project/
├── belay.config.ts        # 선택한 표면·인프라가 채워진 상태로 생성
├── AGENTS.md              # 에이전트용 규칙 — test/ 를 고치지 못하게 하는 문장 포함
├── src/                   # 기존 코드가 있었다면 통째로 이동
└── test/
    ├── support/           # world · hooks · 선택한 표면의 드라이버만
    ├── contracts/         # GraphQL/gRPC 를 골랐다면 스키마 자리
    ├── baselines/         # 브라우저를 골랐을 때만 생성
    └── features/
        └── L0-smoke/
            └── health.feature

생성되는 첫 시나리오는 의도적으로 사소합니다.

# language: ko
기능: 서비스 기동

  시나리오: 헬스체크에 응답한다
    만일 "/health" 를 조회하면
    그러면 응답은 성공이다

명령어

언어

메시지 · CLI 도움말 · 생성되는 스캐폴딩이 모두 BELAY_LANG (en, ko)을 따릅니다. 값이 없으면 로케일을, 그것도 없으면 영어를 씁니다.

belay init                # 영어 Gherkin · 스텝 · AGENTS.md
BELAY_LANG=ko belay init  # 한국어로 생성

Gherkin 파서는 이 설정과 무관하게 ko · en · ja dialect 를 모두 읽습니다. 한국어로 쓴 시나리오를 영어 도구를 보는 사람이 그대로 돌릴 수 있고, 저장소의 예제도 두 언어가 섞여 있어 양쪽 dialect 가 매 CI 실행에서 검증됩니다.

에이전트에게 넘기기

init이 AGENTS.md에 넣는 규칙은 짧습니다. 핵심은 하나 — 채점자와 응시자를 분리하는 것입니다.

## Belay 하네스 규칙

- 구현은 `src/` 안에서만 수정합니다.
- `test/` 는 읽기 전용입니다. 시나리오를 고쳐서 통과시키지 마세요.
- 작업을 마쳤다고 보고하기 전에 `belay run` 을 실행하고 출력을 그대로 첨부하세요.
- 스펙이 잘못되었다고 판단되면 고치지 말고, 근거와 함께 보고만 하세요.

여기까지 오면 반복 구간은 세 줄로 줄어듭니다. 에이전트가 src/를 고치고, belay run이 판정하고, 실패 목록이 다음 할 일이 됩니다. 채점 기준을 스스로 고칠 수 없으므로 구현만 수렴합니다 — 이것이 Belay가 말하는 안전한 바이브 코딩입니다.

belay run --only L0        # 앵커 확인
belay new L1-account/signup # 스펙을 시나리오로 먼저 고정
belay run                   # 실패 목록 = 남은 할 일

02 이미 있는 프로젝트 채택하기

안전망이 가장 절실한 프로젝트는 이미 굴러가고 있는 프로젝트입니다.

Belay는 빈 디렉터리에서만 시작할 수 있는 것이 아닙니다. 이미 돌고 있는 서비스를 가리키면, 코드를 읽어서 원래는 처음부터 설명해야 했을 부분을 채워 넣습니다.

belay init --from ../my-api --link symlink

  ✓ src → ../my-api

  프로젝트에서 읽은 것
    stack      node
    start      npm start --prefix src  (high: scripts.start = "node src/index.js")
    port       4321                    (high: PORT=4321)
    health     /healthz
    surfaces   http
    infra      db · cache              (compose 에서 — 필요한 것만 선언하세요)

포트와 실행 명령, health 경로는 모두 코드에서 나옵니다. 그래서 첫 시나리오는 이 서비스가 따르지 않을지도 모르는 관례가 아니라, 실제로 응답하는 엔드포인트를 두드립니다. 읽어 낸 값에는 어디서 나왔는지가 함께 붙습니다 — 확인할 수 있는 제안이 믿어야 하는 제안보다 낫습니다.

src/를 연결하는 방식

네 가지 방식은 연결한 뒤 코드의 소유가 누구에게 있는지가 다르고, 그에 따라 CI가 스위트를 체크아웃할 수 있는지까지 갈립니다. 남을 대신해 정해 줄 선택이 아닙니다.

symlink로 연결한 src는 .gitignore에 추가됩니다. 레포 바깥을 가리키는 링크를 커밋해서 득 볼 사람이 없습니다. submodule은 커밋되며, CI에서는 actions/checkout@v4에 submodules: true가 필요합니다.

이미 있는 코드를 시나리오로 만들기

belay analyze는 연결된 프로젝트를 읽어 .belay/analysis.md에 체크리스트를 씁니다. 찾아낸 엔드포인트를 L1- 디렉터리가 될 도메인 단위로 묶고, 각각에 성공 경로 후보와 거부 경로 후보를 하나씩 달아 둡니다.

### `L1-orders`

| 표면 | 오퍼레이션 | 위치 |
|---|---|---|
| http | `GET /api/orders`         | src/routes/orders.js |
| http | `POST /api/orders`        | src/routes/orders.js |
| http | `ANY /api/orders/:param`  | src/routes/orders.js |

후보:

- [ ] `POST /api/orders` — 성공 경로: 이후에 참이 되는, 이전에는 아니었던 것은 무엇인가?
- [ ] `POST /api/orders` — 거부 경로: 어떤 입력이 거부되고, 어떤 오류 코드로 거부되는가?

작업을 맡을 에이전트를 위한 skill

init은 같은 skill을 .claude/skills/belay/와 .agent/skills/belay/에 함께 씁니다. 코딩 에이전트가 시작하기 전에 경계를 먼저 읽게 하려는 것입니다 — src/는 다시 써도 되지만, 무언가를 통과시키려고 test/를 고치는 것은 안 됩니다. Belay의 가치는 전부 그 분리 위에 서 있고, 에이전트는 읽으라고 시키지도 않은 README만으로는 그 규칙을 지키지 않습니다.

03 왜 Belay 인가

바이브 코딩의 진짜 병목은 생산 속도가 아니라 회귀에 대한 두려움, 그리고 에이전트가 쓴 코드를 읽는 비용입니다.

에이전트에게 기능을 맡기면 코드는 나옵니다. 문제는 그다음입니다. 리팩터링을 시켜도 되나? 프레임워크를 갈아타도 되나? 이 커밋이 두 달 전에 만든 결제 흐름을 조용히 깨뜨리지는 않았나? 확인할 방법이 없으면 결국 사람이 매번 손으로 눌러 보게 되고, 속도의 이점은 거기서 사라집니다.

기존 방식들은 각자 다른 이유로 이 지점에서 미끄러집니다.

병목의 나머지 절반: 코드를 읽는 일

바이브 코딩은 코드를 쓰는 비용만 낮췄을 뿐, 그 코드를 믿는 비용은 오히려 올려놨습니다. 에이전트는 500줄짜리 diff를 1분 만에 내놓고, 그것을 눈으로 승인하려면 500줄을 전부 읽어야 합니다. 다음 커밋에서도, 그다음 커밋에서도 마찬가지입니다. 검수해야 할 산출물이 우리를 빠르게 만들어 준 바로 그 속도로 함께 늘어납니다.

Belay는 대신 훨씬 작고, 이미 읽을 줄 아는 언어로 쓰인 산출물을 건넵니다.

  시나리오: 이미 사용한 쿠폰은 다시 쓸 수 없다
    먼저 쿠폰 "WELCOME" 은 이미 사용되었다
    만일 그 쿠폰을 장바구니에 적용하면
    그러면 요청은 거절된다
    그리고 장바구니 결제 금액은 그대로다

검수 대상은 이것입니다. 프레임워크도, 클래스 이름도, 제어 흐름도 없고 — 우리가 합의하려는 동작만 남습니다. 문장 열 줄이 구현 천 줄이 해도 되는 일의 범위를 못 박고, 애초에 그 기능을 요구한 사람도 그대로 읽을 수 있습니다.

게다가 이 문장들은 구현에 대한 설명이 아니라 구현에 대한 검사입니다. 스텝은 사용자가 닿을 수 있는 표면만 두드리므로, 스위트가 초록색이라는 건 그 문장들이 실제로 돌아가는 시스템에서 참이라는 뜻입니다. 무언가를 목으로 발라 맞춰 놓은 결과가 아닙니다. 스펙을 검수하고, 구현 검수는 스위트에 맡기십시오.

04 핵심 개념

등반자는 자유롭게 오르고, 확보자는 로프를 잡습니다.

여기서 따라 나오는 세 가지 원칙이 Belay의 전부입니다.

1. 블랙박스 — 테스트는 배포된 산출물이 노출하는 인터페이스로만 대상을 다룹니다. 소스 임포트, 내부 함수 호출, 내부 DB 직접 조작 모두 금지.
2. 재현 가능 — 인프라 기동부터 정리까지 한 명령에 담깁니다. 내 노트북에서 되는 것과 CI에서 되는 것이 같아야 합니다.
3. 스펙이 곧 테스트 — .feature는 사람이 읽는 명세인 동시에 기계가 돌리는 검증입니다. 둘이 갈라질 여지를 없앱니다.

05 프로젝트 구조

최상단은 언제나 src와 test 둘뿐입니다.

# 프로젝트 루트
Belay/
├── belay.config.ts        # 앵커: src를 어떻게 띄우고 두드릴지
├── docs/
│   └── index.html
│
├── src/                   # ── 검증 대상. 별도 레포의 루트와 동일한 모습 ──
│   ├── package.json           # Node? Kotlin? Go? Rust? 무엇이든 상관없음
│   ├── Dockerfile
│   └── ...                    # Belay는 이 안을 들여다보지 않는다
│
└── test/                  # ── 블랙박스 시나리오 ──
    ├── support/
    │   ├── world.ts           # 시나리오별 컨텍스트 (드라이버, 상태)
    │   ├── hooks.ts           # Before / After, 시나리오 간 격리
    │   ├── steps/             # 프로토콜 공통 스텝 (상태코드, JSONPath 단언 등)
    │   └── drivers/           # Surface 어댑터 — 도메인 로직 없음
    │       ├── http.ts
    │       ├── graphql.ts
    │       ├── grpc.ts
    │       ├── ws.ts          # WebSocket / SSE 등 스트리밍
    │       ├── browser.ts     # 페이지 조작 · 캡처 · 시각 검증
    │       ├── cli.ts
    │       └── mocks.ts       # mock infra 조작 · 수신 호출 검증
    │
    ├── contracts/             # 프로토콜 스키마 — 드라이버가 타입을 얻는 곳
    │   ├── schema.graphql
    │   ├── order.proto
    │   └── pg.openapi.yaml    # 외부 결제사 스텁의 계약
    │
    ├── baselines/             # 승인된 스크린샷 — 변경은 리뷰 대상
    │   └── L2-checkout/
    │       ├── cart-empty.desktop.png
    │       └── cart-empty.mobile.png
    │
    └── features/
        ├── L0-smoke/
        │   └── health.feature
        ├── L1-account/
        │   ├── signup.feature      # HTTP
        │   ├── signup.steps.ts
        │   └── login.feature
        ├── L1-catalog/
        │   ├── search.feature      # GraphQL
        │   └── search.steps.ts
        ├── L2-order/
        │   ├── checkout.feature    # gRPC + WebSocket
        │   └── checkout.steps.ts
        ├── L2-ui-checkout/
        │   ├── cart.feature        # 브라우저 여정 + 시각 검증
        │   └── cart.steps.ts
        └── L3-cross/
            └── signup-to-first-order.feature

06 실행 계약

루트 설정 파일 하나가 "이 프로젝트를 테스트 가능한 상태로 만드는 법"을 전부 담습니다.

Belay가 src/에 대해 아는 유일한 것은 이 파일입니다. 어떻게 빌드하고, 무엇에 의존하고, 언제 준비된 것으로 볼지, 그리고 어떤 창구로 두드릴지. 여기 적히지 않은 내부 사정은 테스트가 알 수 없습니다 — 그게 의도입니다.

import { defineConfig } from '@beoks/belay';

export default defineConfig({
  // 1. src가 필요로 하는 주변 환경 — 컨테이너, mock 서버, 무엇이든
  infra: [
    { name: 'postgres', image: 'postgres:16', ports: ['5432'],
      env: { POSTGRES_PASSWORD: 'test' },
      ready: { tcp: '5432' } },

    { name: 'payment-gateway', // 외부 결제사 스텁
      command: 'npx prism mock ./test/contracts/pg.openapi.yaml -p 4010',
      ready: { http: 'http://localhost:4010/__health' } },
  ],

  // 2. src를 띄우는 법. 명령어 한 줄이면 충분하다
  app: {
    build: 'docker build -t belay-sut ./src',
    start: 'docker run --rm -p 8080:8080 --env-file .belay/env belay-sut',
    env: {
      DATABASE_URL: 'postgres://postgres:test@localhost:5432/app',
      PAYMENT_BASE_URL: 'http://localhost:4010',
    },
    // 준비 완료 판정. 이게 없으면 테스트는 항상 경합한다
    ready: { http: 'http://localhost:8080/health', timeoutMs: 60_000 },
  },

  // 3. 테스트가 대상을 두드릴 수 있는 유일한 창구들
  //    여기 선언된 것만 존재한다. 선언되지 않은 경로로 닿으면 블랙박스가 깨진다.
  surfaces: {
    http:    { baseUrl: 'http://localhost:8080' },
    graphql: { endpoint: 'http://localhost:8080/graphql',
               schema: './test/contracts/schema.graphql' },
    grpc:    { address: 'localhost:9090',
               proto: './test/contracts/order.proto', reflection: false },
    ws:      { url: 'ws://localhost:8080/ws', subprotocol: 'graphql-ws' },
    queue:   { kind: 'kafka', brokers: ['localhost:9092'] },
    cli:     { command: 'docker run --rm belay-sut app-cli' },

    // 프론트엔드 표면 — 사용자가 실제로 보는 화면
    browser: { baseUrl: 'http://localhost:3000',
               engine: 'chromium',
               viewports: { desktop: [1280, 800], mobile: [390, 844] },
               locale: 'ko-KR', timezone: 'Asia/Seoul', colorScheme: 'light' },
  },

  // 4. 시각 검증 정책
  visual: {
    baselineDir: 'test/baselines',
    diff:      { threshold: 0.01, ignore: ['[data-belay-volatile]'] },
    interpret: { enabled: true, gate: false },  // 시각 해석은 기본 비게이트 — 10장 참조
    capture:   { onFailure: 'screenshot+dom+video' },
  },

  // 5. 환경 제어 — 바깥에서 만들 수 없는 상태를 만드는 선언된 창구
  control: {
    clock:   { via: 'http', endpoint: '/__test/clock' },   // SUT가 제공하는 테스트 전용 계약
    seed:    { via: 'http', endpoint: '/__test/seed' },
    faults:  { targets: ['postgres', 'payment-gateway'] },      // 지연·단절·재시작 주입 대상
    determinism: { randomSeed: 1337, freezeTimezone: 'Asia/Seoul' },
  },

  // 6. 시나리오 위치
  suite: {
    features: 'test/features/**/*.feature',
    steps:    'test/**/*.steps.ts',
    support:  'test/support/**/*.ts',
  },

  // 7. 시나리오 사이 격리 — 상태 누수는 신뢰를 갉아먹는다
  isolation: {
    between: 'scenario',
    // 셸 명령이거나, 선언된 창구로 보내는 요청. 둘 다 SUT 내부를 건드리지 않는다.
    reset:   { http: '/__test/seed', body: { data: { todos: [] } } },
    browser: true,    // 쿠키·스토리지·세션까지 매번 새 컨텍스트
    mocks:   true,    // 스텁 프로그래밍과 수신 기록을 함께 초기화
  },

  // 8. 데드라인 — 멈춘 스텝 하나가 실행 전체를 인질로 잡지 못하게
  timeouts: { step: 30_000, scenario: 120_000, hook: 30_000 },

  // 9. 결과와 정리
  report:   { formats: ['html', 'junit', 'json'], outDir: '.belay/reports', trace: true },
  teardown: { keepOnFailure: true },
});

07 실행 라이프사이클

belay run 한 번에 벌어지는 일 — 올라가고, 확보하고, 내려옵니다.

08 시나리오 작성

Gherkin으로 씁니다. 사람이 읽는 명세와 기계가 돌리는 검증이 같은 문장이고, 그래서 src/를 한 번도 열지 않는 사람도 스펙을 검수할 수 있습니다.

# language: ko
기능: 이메일 회원가입

  등록되지 않은 이메일로 가입을 요청하면 계정이 생성되고
  인증 메일이 발송된다. 이미 쓰인 이메일은 거절한다.

  배경:
    먼저 메일 발송 스텁이 비어 있다

  시나리오: 신규 이메일로 가입에 성공한다
    먼저 "chulsoo@example.com" 은 등록되지 않은 이메일이다
    만일 "chulsoo@example.com" 으로 회원가입을 요청하면
    그러면 응답 상태코드는 201 이다
    그리고 응답 본문에 계정 식별자가 포함된다
    그리고 "chulsoo@example.com" 으로 인증 메일이 1건 발송된다

  시나리오: 이미 사용 중인 이메일은 거절한다
    먼저 "chulsoo@example.com" 으로 가입된 계정이 있다
    만일 "chulsoo@example.com" 으로 회원가입을 요청하면
    그러면 응답 상태코드는 409 이다
    그리고 인증 메일은 발송되지 않는다

  시나리오 개요: 잘못된 형식의 이메일은 거절한다
    만일 "<입력>" 으로 회원가입을 요청하면
    그러면 응답 상태코드는 400 이다

    예:
      | 입력            |
      | not-an-email    |
      | @example.com    |
      |                 |

좋은 시나리오의 조건

09 Step Definition

TypeScript로만 작성합니다. src가 어떤 언어든, 확보자의 언어는 하나로 고정합니다.

스텝 구현은 얇아야 합니다. 문장을 드라이버 호출로 번역하고 응답을 단언하는 것까지가 전부이고, 도메인 규칙을 여기에 다시 구현하기 시작하면 테스트가 두 번째 구현체가 되어 버립니다.

import { Given, When, Then, expect } from '@beoks/belay';
import type { AppWorld } from '../../support/world';

Given('{string} 은 등록되지 않은 이메일이다', async function (this: AppWorld, email: string) {
  // 공개 API로만 확인한다. DB를 직접 뒤지지 않는다.
  const res = await this.http.get(`/api/v1/accounts?email=${encodeURIComponent(email)}`);
  expect(res.status).toBe(404);
  this.ctx.email = email;
});

Given('{string} 으로 가입된 계정이 있다', async function (this: AppWorld, email: string) {
  const res = await this.http.post('/api/v1/accounts', { email, password: 'P@ssw0rd!' });
  expect(res.status).toBe(201);
  this.ctx.email = email;
  await this.mock.mail.clear();   // 준비 과정의 부수효과는 관찰 대상이 아니다
});

When('{string} 으로 회원가입을 요청하면', async function (this: AppWorld, email: string) {
  this.last = await this.http.post('/api/v1/accounts', { email, password: 'P@ssw0rd!' });
});

Then('응답 상태코드는 {int} 이다', function (this: AppWorld, status: number) {
  expect(this.last.status).toBe(status);
});

Then('{string} 으로 인증 메일이 {int}건 발송된다',
  async function (this: AppWorld, to: string, count: number) {
    // 메일 스텁은 우리 것 — 수신함을 직접 확인해도 블랙박스는 유지된다
    const mails = await this.mock.mail.waitFor({ to, timeoutMs: 5_000 });
    expect(mails).toHaveLength(count);
});

import { World, setWorldConstructor } from '@beoks/belay';

export class AppWorld extends World {
  // World 는 이미 표면별 드라이버를 갖고 있습니다:
  //   this.http · this.gql · this.ws · this.cli · this.page
  //   this.mock.<이름>  — 선언한 stub / mail
  //   this.control       — clock · seed · faults
  //   this.last          — 마지막 Exchange (프로토콜 공통 스텝이 참조)
  // 설정에 없는 표면에 접근하면 무엇을 선언해야 하는지 알려주며 실패합니다.

  // 여기에는 시나리오 안에서만 유효한 상태와 얇은 헬퍼만 둡니다.
  token?: string;

  async authenticate(email: string, password = 'P@ssw0rd!'): Promise<void> {
    const response = await this.http.post('/api/v1/sessions', { email, password });
    this.token = (response.body as { token?: string })?.token;
  }
}

setWorldConstructor(AppWorld);

10 프로토콜 드라이버

HTTP · GraphQL · gRPC · WebSocket — 표면은 달라도 시나리오 문장은 같은 모양이어야 합니다.

백엔드는 하나의 프로토콜만 쓰지 않습니다. 조회는 GraphQL, 내부 호출은 gRPC, 실시간 갱신은 WebSocket, 관리 기능은 REST인 서비스가 흔합니다. 프로토콜마다 단언 방식이 제각각이면 시나리오는 금세 기술 문서가 되고, src/를 갈아엎을 때 같이 무너집니다.

그래서 Belay의 모든 드라이버는 동일한 Exchange를 반환합니다. 상태·본문·메타데이터가 같은 모양으로 정규화되므로, 상태코드나 JSONPath 단언 같은 공통 스텝을 프로토콜을 넘나들며 재사용할 수 있습니다.

정규화된 교환 결과

export interface Exchange<T = unknown> {
  ok: boolean;
  status: number;          // HTTP status · gRPC code · WS close code로 정규화
  body: T;                  // GraphQL은 data, gRPC는 응답 메시지
  errors?: { code: string; message: string; path?: string[] }[];
  meta: Record<string, string>;   // 헤더 · trailer · 프레임 메타
  elapsedMs: number;
  // 모든 Exchange는 자동으로 트레이스에 기록된다 — 별도 로깅 불필요
}

덕분에 이런 스텝을 한 번만 정의해 전 프로토콜에서 씁니다.

Then('응답은 성공이다', function (this: AppWorld) {
  expect(this.last.ok).toBe(true);
});

Then('오류 코드는 {string} 이다', function (this: AppWorld, code: string) {
  expect(this.last.errors?.[0].code).toBe(code);   // GraphQL · gRPC · HTTP 공통
});

Then('응답의 {string} 는 {string} 이다',
  function (this: AppWorld, path: string, value: string) {
    expect(jsonPath(this.last.body, path)).toEqual(coerce(value));
});

프로토콜별 스텝 구현

// ── GraphQL ─────────────────────────────────────────────
When('{string} 로 상품을 검색하면', async function (this: AppWorld, q: string) {
  this.last = await this.gql.query(`
    query Search($q: String!) { search(query: $q) { id name price } }
  `, { q });   // contracts/schema.graphql 로 타입 검증됨
});

// ── gRPC (unary) ────────────────────────────────────────
When('주문을 확정하면', async function (this: AppWorld) {
  this.last = await this.grpc.call('order.OrderService/PlaceOrder', {
    cartId: this.ctx.cartId, idempotencyKey: this.ctx.key,
  });
});

Then('gRPC 상태는 {string} 이다', function (this: AppWorld, code: string) {
  expect(this.last.meta['grpc-status-name']).toBe(code);   // FAILED_PRECONDITION 등
});

// ── WebSocket ───────────────────────────────────────────
Given('주문 상태 채널을 구독하고 있다', async function (this: AppWorld) {
  this.sub = await this.ws.subscribe({ topic: 'order', id: this.ctx.cartId });
});

Then('{int}초 안에 주문 상태 {string} 알림을 받는다',
  async function (this: AppWorld, sec: number, status: string) {
    // sleep이 아니라 조건 대기 — 스트리밍에서 고정 대기는 곧 플레이키다
    const msg = await this.sub.waitFor(
      (m) => m.type === 'order.status' && m.status === status,
      { timeoutMs: sec * 1000 },
    );
    expect(msg.orderId).toBe(this.last.body.orderId);
});

Then('그 외 주문 알림은 오지 않는다', async function (this: AppWorld) {
  await expect(this.sub.quietFor({ ms: 1_000 })).resolves.toBe(true);
});

시나리오에서는 프로토콜의 흔적이 거의 드러나지 않습니다.

# language: ko
기능: 주문 확정

  시나리오: 재고가 있으면 주문이 확정되고 실시간으로 통보된다
    먼저 "노트북 거치대" 가 3개 재고로 등록되어 있다
    그리고 주문 상태 채널을 구독하고 있다
    만일 주문을 확정하면
    그러면 응답은 성공이다
    그리고 5초 안에 주문 상태 "CONFIRMED" 알림을 받는다
    그리고 그 외 주문 알림은 오지 않는다

  시나리오: 재고가 부족하면 주문을 거절한다
    먼저 "노트북 거치대" 가 0개 재고로 등록되어 있다
    만일 주문을 확정하면
    그러면 gRPC 상태는 "FAILED_PRECONDITION" 이다
    그리고 오류 코드는 "OUT_OF_STOCK" 이다

11 브라우저와 시각 검증

프론트엔드의 공개 인터페이스는 화면입니다. 그래서 화면을 열고, 누르고, 찍고, 읽습니다.

프론트엔드 프로젝트에서 "블랙박스"는 곧 브라우저입니다. Belay는 실제 엔진을 띄워 사용자가 하는 그대로 조작하고, 결과를 세 가지 층위로 검증합니다. 층위마다 결정성이 다르고, 게이트로 삼을 수 있는 범위도 다릅니다.

시나리오

# language: ko
기능: 장바구니 화면

  배경:
    먼저 "chulsoo@example.com" 으로 로그인한 상태로 "/cart" 를 연다

  시나리오: 담은 상품이 없으면 빈 상태를 안내한다
    그러면 "장바구니가 비어 있습니다" 문구가 보인다
    그리고 "주문하기" 버튼은 비활성 상태다
    그리고 화면 "cart-empty" 는 승인된 기준 이미지와 같다

  시나리오: 수량을 바꾸면 합계가 즉시 갱신된다
    먼저 장바구니에 "노트북 거치대" 가 1개 담겨 있다
    만일 "수량" 을 3 으로 바꾸면
    그러면 "합계" 영역에 "87,000원" 이 보인다
    그리고 콘솔 오류가 발생하지 않았다

  시나리오 개요: 좁은 화면에서도 주문 버튼이 가려지지 않는다
    먼저 장바구니에 상품이 5개 담겨 있다
    만일 화면 폭을 "<뷰포트>" 로 바꾸면
    그러면 "주문하기" 버튼을 누를 수 있다
    그리고 화면 "cart-filled" 를 읽으면 "가격이 잘리거나 겹쳐 보이지 않는다"

    예:
      | 뷰포트   |
      | desktop  |
      | mobile   |

브라우저 스텝

When('{string} 버튼을 누르면', async function (this: AppWorld, name: string) {
  // 역할과 이름으로만 찾는다. CSS 클래스·컴포넌트 이름은 프레임워크를 바꾸면 사라진다.
  await this.page.byRole('button', { name }).click();
});

Then('{string} 문구가 보인다', async function (this: AppWorld, text: string) {
  await expect(this.page.byText(text)).toBeVisible({ timeoutMs: 5_000 });
});

Then('{string} 버튼은 비활성 상태다', async function (this: AppWorld, name: string) {
  await expect(this.page.byRole('button', { name })).toBeDisabled();
});

// ── 2단계: 시각 회귀 (결정적, 게이트) ──────────────────────
Then('화면 {string} 는 승인된 기준 이미지와 같다',
  async function (this: AppWorld, name: string) {
    await this.page.waitForStable();   // 애니메이션·폰트·이미지 로드 종료까지
    const shot = await this.page.capture(name);   // 리포트에 자동 첨부
    await expect(shot).toMatchBaseline();       // 없으면 실패 — 승인은 별도 명령으로
});

// ── 3단계: 시각 해석 (비결정적, 기본 경고) ─────────────────
Then('화면 {string} 를 읽으면 {string}',
  async function (this: AppWorld, name: string, claim: string) {
    const shot = await this.page.capture(name);
    const v = await shot.interpret(claim);   // { holds, reason, confidence }
    this.report.note('visual-interpretation', { claim, ...v });
    if (belay.visual.interpret.gate) expect(v.holds).toBe(true);
});

// 브라우저 부수 신호도 관찰 대상이다
Then('콘솔 오류가 발생하지 않았다', function (this: AppWorld) {
  expect(this.page.consoleErrors()).toEqual([]);
});

선택자 규칙

프론트엔드에서 블랙박스를 지키는 핵심은 무엇으로 요소를 찾느냐입니다. React에서 Svelte로 옮겨도 살아남는 기준으로만 찾아야 시나리오가 정답지 역할을 계속할 수 있습니다.

프론트 단독 프로젝트

src/가 프론트엔드만인 경우, 백엔드 자리를 계약 기반 mock이 대신합니다. test/contracts/의 OpenAPI·GraphQL 스키마로 스텁을 띄우고 브라우저의 네트워크를 그쪽으로 돌리면, 서버 없이도 로딩·에러·빈 상태·지연 같은 화면 분기를 전부 재현할 수 있습니다.

// 화면 분기를 만들기 위해 백엔드 응답을 조작한다 — mock은 우리 것이므로 허용
Given('상품 목록 조회가 {int}ms 지연된다', async function (this: AppWorld, ms: number) {
  await this.mock.api.onGet('/api/v1/products').delay(ms);
});

Given('상품 목록 조회가 실패한다', async function (this: AppWorld) {
  await this.mock.api.onGet('/api/v1/products').reply(503);
});

// → "그러면 재시도 버튼이 보인다" 같은 화면 계약을 결정적으로 검증할 수 있다

12 테스트 환경 제어

바깥에서 만들 수 없는 상황을, 내부를 뚫지 않고 만들어 냅니다.

정말 확인하고 싶은 것들은 대개 평범한 요청으로는 재현되지 않습니다. 30일 뒤에 만료되는 쿠폰, 결제사가 502를 뱉는 순간, DB가 잠깐 끊겼을 때의 재시도. 여기서 흔한 유혹이 "테스트에서 DB를 직접 건드리자"인데, 그 순간 포팅 가능성이 사라집니다.

Belay는 대신 제어 표면을 씁니다. 조작 대상은 두 종류이고, 둘의 규칙이 다릅니다.

# language: ko
기능: 결제사 장애 대응

  시나리오: 결제사가 일시 장애면 주문을 보류하고 한 번만 재청구한다
    먼저 장바구니에 상품이 담겨 있다
    그리고 결제사가 처음 2번의 요청에 502 로 응답한다
    만일 주문을 확정하면
    그러면 응답은 성공이다
    그리고 30초 안에 주문 상태 "PENDING_PAYMENT" 알림을 받는다
    그리고 결제사에 도달한 청구 요청은 동일한 멱등키를 갖는다

  시나리오: 미결제 주문은 3일 뒤 자동 취소된다
    먼저 "PENDING_PAYMENT" 상태의 주문이 있다
    만일 시간이 3일 흐르면
    그러면 주문 상태는 "CANCELLED" 이다
    그리고 재고가 원래대로 복구된다

Given('결제사가 처음 {int}번의 요청에 {int} 로 응답한다',
  async function (this: AppWorld, times: number, status: number) {
    await this.mock.pg.onPost('/charges').replyTimes(times, status).thenPassthrough();
});

When('시간이 {int}일 흐르면', async function (this: AppWorld, days: number) {
  await this.control.clock.advance(`P${days}D`);
  await this.control.drainScheduledJobs();   // 배치가 돌 때까지 조건 대기
});

Then('결제사에 도달한 청구 요청은 동일한 멱등키를 갖는다', async function (this: AppWorld) {
  const keys = (await this.mock.pg.calls('POST /charges'))
    .map((c) => c.headers['idempotency-key']);
  expect(new Set(keys).size).toBe(1);   // 몇 번 재시도했든 중복 청구는 없어야 한다
});

13 블랙박스 경계

무엇을 만져도 되고 무엇을 만지면 안 되는지에 대한 명시적 선.

한 가지 예외적 회색지대는 테스트 전용 인터페이스입니다. 시간 이동이나 시드 데이터 주입처럼 바깥에서 도저히 만들 수 없는 상태가 있다면, 내부를 뚫는 대신 /__test/clock 같은 명시적이고 문서화된 창구를 SUT가 제공하게 하십시오. 포팅 대상도 같은 창구를 구현해야 하므로 계약의 일부로 남습니다.

14 시나리오 계층

디렉터리가 곧 계층이고, 계층이 곧 실행 순서이자 실패 해석의 문법입니다.

계층이 나뉘어 있으면 실패가 곧 진단이 됩니다. L1은 다 통과하는데 L2가 무너졌다면 개별 기능이 아니라 상태 전이나 연결이 문제라는 뜻이고, 에이전트에게 넘길 때도 "어디를 보라"는 정보가 함께 갑니다. 빠른 피드백이 필요하면 belay run --upto L1처럼 계층을 잘라 실행합니다.

15 포팅과 재작성

Belay가 존재하는 진짜 이유.

시나리오가 src/ 바깥에 있고 공개 인터페이스로만 말한다면, src/는 교체 가능한 부품이 됩니다. Express로 시작한 프로토타입을 Kotlin/Spring으로 다시 쓰든, REST를 GraphQL로 바꾸든, React 화면을 Svelte로 옮기든, 절차는 같습니다.

1. 기준선 확보 — 현재 src/로 전 계층 통과를 확인하고 리포트를 저장합니다. 통과하지 않는 스펙은 기준이 될 수 없습니다.
2. 대상 교체 — 새 구현을 src/에 놓고 belay.config.ts의 build/start만 새 스택에 맞게 바꿉니다. surfaces와 test/는 한 글자도 손대지 않습니다.
3. 계층 순 점등 — L0부터 통과시켜 올라갑니다. 각 계층 통과가 곧 진척도이고, 남은 실패 목록이 곧 남은 할 일 목록입니다.
4. 완료 판정 — 전 계층 통과 = 포팅 완료. "다 옮긴 것 같다"가 아니라 확인된 사실입니다.

표면을 바꿀 때

에이전트에게 맡길 때도 같은 구조가 그대로 작동합니다. test/는 읽기 전용으로 주고 src/만 수정 권한을 준 뒤 belay run을 반복하게 하면, 채점 기준을 스스로 고칠 수 없는 상태에서 구현만 수렴시키게 됩니다.

16 결과와 신뢰

통과했다는 사실보다, 통과를 믿을 수 있다는 사실이 중요합니다.

$ belay run

  ▸ infra     postgres ✓ 1.8s   kafka ✓ 4.1s   payment-gateway ✓ 0.6s
  ▸ build     belay-sut ✓ 24.1s
  ▸ ready     http://localhost:8080/health ✓ 3.2s
  ▸ surfaces  http · graphql · grpc · ws · browser(chromium) ✓

  L0-smoke          2 시나리오   2 통과
  L1-account       14 시나리오  14 통과
  L1-catalog        6 시나리오   6 통과            graphql
  L2-order          9 시나리오   8 통과   1 실패   grpc · ws
  L2-ui-checkout    7 시나리오   7 통과            browser · ⚠ 1 시각 경고
  L3-cross          4 시나리오   4 통과

  ✗ L2-order/checkout.feature:31  재고가 부족하면 주문을 거절한다
      그러면 gRPC 상태는 "FAILED_PRECONDITION" 이다
        expected FAILED_PRECONDITION, received INTERNAL
        → .belay/reports/2026-07-29T20-14/L2-order-31/

  ⚠ L2-ui-checkout/cart.feature:24  [시각 해석 · 게이트 아님]
      주장: "가격이 잘리거나 겹쳐 보이지 않는다" — 성립하지 않음 (confidence 0.71)
      "mobile 뷰포트에서 합계 금액 끝자리가 컨테이너 밖으로 넘침"
      → cart-filled.mobile.png · 확인 후 구조 단언이나 baseline으로 승격 권장

  ▸ teardown  keepOnFailure=true — 컨테이너 유지 (belay down 으로 정리)

  41/42 통과 · 경고 1 · 소요 2m 38s · exit 1

17 이 문서의 주장은 어디서 검증되는가

설계 문서가 코드보다 앞서 나가면 첫 사용자가 배신당합니다. 각 주장이 어느 예제에서 실제로 돌아가는지 적어 둡니다.

examples/ 는 전시장이 아니라 회귀 스위트입니다. npm run examples 가 사용자와 똑같은 방식으로 전부 실행하고, CI 는 여기서 실패하면 빌드를 깨뜨립니다.

아직 구현되지 않은 것

동작하지 않는 것, 그리고 의도적으로 지원하지 않는 것을 발견되게 두는 대신 여기에 명시합니다.

• 큐(Kafka) 드라이버 — 1.0 에서 구현되었습니다 (surfaces.queue, 선택적 peer kafkajs): key·헤더를 실은 발행, latest 오프셋 구독과 WebSocket 과 동일한 waitFor/quietFor/mark 재생 계약, admin API 를 통한 토픽 자동 생성. 실제 단일 노드 Kafka(apache/kafka 3.8, KRaft)로 현장 검증했습니다 — 발행→소비 왕복, key/헤더 보존, latest 오프셋 의미론, 침묵 단언. 버퍼링 의미론은 선언된 클라이언트 경계에 대한 단위 테스트로 고정되어 있습니다. Docker 인프라 경로와 마찬가지로 상시 검증은 아닙니다: 예제는 의도적으로 Docker 없이 돌기 때문에, 매 실행 실제 브로커를 두드리는 예제는 없습니다.
• Docker 인프라 경로 — image: 로 컨테이너를 띄우는 코드는 있고 현장에서 한 차례 검증되었습니다(RealWorld showcase의 Postgres 컨테이너, macOS/colima). 다만 예제가 전부 Docker 없이 도는 방식이라 상시 검증되고 있지는 않습니다. command: · stub: · mail: 경로를 우선 쓰세요. 1.0 부터 ports: ['15432:5432'] 처럼 호스트≠컨테이너 매핑을 선언할 수 있고, 준비 판정 명령이 생성된 컨테이너 이름을 참조할 수 있습니다 — ready: { command: 'docker exec {container} pg_isready' }. VM 포트포워더 뒤에서는 TCP 가 서비스보다 먼저 열리므로 이것이 정직한 프로브입니다.

Windows

네이티브로 지원합니다 (이전에는 거부했습니다). 정리(teardown)는 POSIX 가 프로세스 그룹을 죽이는 자리에서 taskkill /T 로 프로세스 트리 전체를 죽이고, belay down 은 선언된 포트를 아직 쥐고 있는 프로세스까지 추적해 정리합니다. 플랫폼 특성 두 가지: 종료 시그널은 POSIX 개념이라 Windows 에서는 모든 종료가 강제 종료입니다 — 종료 전 정리 시간이 필요한 앱이라면 그 시간을 얻지 못합니다. 그리고 --link symlink 는 심볼릭 링크에 개발자 모드가 필요한 환경에서 디렉터리 정션(junction)으로 대체됩니다. WSL2 도 계속 완전히 지원됩니다.

18 용어집

문서 전반에서 쓰는 말들.