Bruno E2e Builder

bruno-e2e-builder

OpenAPI仕様からBruno CLI実行可能なE2Eテストファイルを生成する。

生成されるフォルダ構造

e2e/
├── bruno.json                      # コレクション設定（自動生成）
├── environments/
│   └── local.bru                   # 環境変数（自動生成）
├── api/                            # APIインターフェーステスト（自動生成）
│   └── {tag}/
│       └── {method}-{path}/        # エンドポイント毎のフォルダ
│           ├── 001. {summary}.bru  # 正常系テスト（シーケンシャル、001-099）
│           ├── 002. {summary} - variant.bru  # 追加の正常系（補完で追加）
│           ├── 101. error - 400 Bad Request.bru  # エラー系（単発、101-199）
│           └── 102. error - 401 Unauthorized.bru # エラー系（単発）
└── scenario/                       # シナリオテスト（手動 or スキャフォールド）
    └── {use-case}/                 # ユースケース毎のフォルダ（リソースを跨ぐ操作）
        ├── 001. setup - {step}.bru # 1エンドポイント = 1ファイル
        ├── 002. {step}.bru
        └── 003. teardown - {step}.bru

ファイル命名規則: {連番3桁}. {タイトル}.bru 連番の昇順 = Bruno CLIの実行順 = bru ファイルに記述した seq の値。

api/ の2種類のテスト:

• 正常系（001-099）: 1エンドポイントのみ呼ぶ。シーケンシャルに実行（後のテストが前の結果を使うこともある）
• エラー系（101-199）: 1エンドポイントのみ呼ぶ。独立した単発テスト（順序不問）

scenario/ の役割:

• RESTリソースを複数跨いで操作するユースケース単位でフォルダを作る
• フォルダ内に1エンドポイント1ファイルを並べる

ステップ1: APIテストの自動生成

OpenAPIファイルから e2e/api/ 配下のテストを一括生成する:

python .github/skills/bruno-e2e-builder/scripts/generate_e2e.py <openapi_file> [options]

# 最小実行
python .github/skills/bruno-e2e-builder/scripts/generate_e2e.py openapi.yaml

# 環境・URL指定
python .github/skills/bruno-e2e-builder/scripts/generate_e2e.py api/spec.yaml \
  --output-dir ./e2e --env staging --base-url https://staging.example.com

生成物:

• e2e/bruno.json - コレクション設定
• e2e/environments/{env}.bru - 環境変数テンプレート
• e2e/api/{tag}/{method}-{path}/*.bru - エンドポイント毎に正常系1件＋OpenAPIのエラー定義から複数件

ステップ2: シナリオテストのスキャフォールド（任意）

RESTリソースを複数跨ぐユースケースの結合テストを生成する:

python .github/skills/bruno-e2e-builder/scripts/scaffold_scenario.py \
  --name user-registration \
  --output-dir ./e2e/scenario \
  --step "setup create-test-data POST /users" \
  --step "main register-user POST /auth/register" \
  --step "verify get-profile GET /users/{id}" \
  --step "teardown delete-user DELETE /users/{id}"

ステップ形式: "<type> <name> <METHOD> <path>"

• type: setup / main / verify / teardown（ファイル名プレフィックスに使用）

生成物: e2e/scenario/{name}/001. setup - create-test-data.bru ... など

各ファイルは1エンドポイントのみを呼ぶ。ユースケース内のリソース操作の流れを表現する。

ステップ3: テストの補完（ユーザー指示による追加）

自動生成後、不足しているテストケースを指示に応じて追加できる:

python .github/skills/bruno-e2e-builder/scripts/add_test.py \
  --dir <エンドポイントフォルダ> \
  --type normal|error|scenario \
  --name <テスト名> \
  --method <METHOD> \
  --path <path> \
  [--status <code>]

# 正常系のバリエーションを追加（オプションフィールドあり）
python .github/skills/bruno-e2e-builder/scripts/add_test.py \
  --dir e2e/api/users/post-users \
  --type normal \
  --name "Create User - with optional fields" \
  --method POST --path /users --status 201

# エラー系を追加（403 Forbidden）
python .github/skills/bruno-e2e-builder/scripts/add_test.py \
  --dir e2e/api/users/post-users \
  --type error \
  --name "403 Forbidden" \
  --method POST --path /users --status 403

# シナリオにステップを追加
python .github/skills/bruno-e2e-builder/scripts/add_test.py \
  --dir e2e/scenario/user-registration \
  --type scenario \
  --name "verify - get profile" \
  --method GET --path /users/{id} --status 200

シーケンス番号は既存ファイルを自動スキャンして次の空き番号が割り当てられる。

補完のワークフロー

ユーザーから「〇〇のテストが足りない」と言われたとき:

1. 対象フォルダを特定: e2e/api/{tag}/{method}-{path}/ または e2e/scenario/{use-case}/
2. 既存ファイルを確認: Glob ツールで *.bru を列挙し、不足しているケースを把握
3. add_test.py を実行: 必要な --type, --name, --status を指定して追加
4. TODOを埋める: 生成されたファイルを Edit ツールでリクエストボディ・アサーションを補完

ステップ4: 環境変数の設定

生成された e2e/environments/local.bru を編集:

vars {
  baseUrl: http://localhost:8080
}

vars:secret [
  accessToken
]

ステップ5: Bruno CLIで実行

# インストール（初回のみ）
npm install -g @usebruno/cli

# 特定エンドポイントのテスト全件
bru run e2e/api/users/get-users --env local

# タグ（リソース）配下のテスト全件
bru run e2e/api/users --env local --recursive

# APIテスト全件
bru run e2e/api --env local --recursive

# シナリオテスト
bru run e2e/scenario/user-registration --env local

# 全E2E
bru run e2e --env local --recursive

生成後の確認・修正ポイント

スクリプトはスケルトンを生成する。以下を確認して補完する:

1. アサーション - 正常系はステータスコードのみ。レスポンスボディの検証を追加する
2. エラーボディ - エラー系の body:json は // TODO のまま。エラーを引き起こす値を入力する
3. 変数の引き継ぎ - script:post-response ブロックで、作成したリソースのIDを後続ステップへ渡す
4. 認証 - accessToken は vars:secret 管理。Bearer token以外が必要なら auth {} ブロックを使う
5. シナリオ順序 - スキャフォールドはテンプレートのみ。実際のフローに合わせて調整する

BRUファイル形式リファレンス

詳細: references/bru-format.md

GET リクエスト（最小構成）

meta {
  name: Get Users
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/users
  body: none
  auth: none
}

headers {
  Authorization: Bearer {{accessToken}}
}

tests {
  test("should return 200", function() {
    expect(res.status).to.equal(200);
  });
}

POST リクエスト（JSONボディ + 変数引き渡し）

meta {
  name: Create User
  type: http
  seq: 1
}

post {
  url: {{baseUrl}}/api/users
  body: json
  auth: none
}

headers {
  Content-Type: application/json
  Authorization: Bearer {{accessToken}}
}

body:json {
  {
    "name": "Test User",
    "email": "test@example.com"
  }
}

tests {
  test("should return 201", function() {
    expect(res.status).to.equal(201);
  });
}

script:post-response {
  bru.setVar("createdUserId", res.body.id);
}

エラー系テスト例（401 Unauthorized）

meta {
  name: error - 401 Unauthorized
  type: http
  seq: 101
}

post {
  url: {{baseUrl}}/api/users
  body: json
  auth: none
}

headers {
  Content-Type: application/json
}

body:json {
  {
    "name": "Test User",
    "email": "test@example.com"
  }
}

tests {
  test("should return 401", function() {
    expect(res.status).to.equal(401);
  });
}