Claude Code で振る舞い駆動開発（BDD）を本番実装する — Gherkin シナリオ自動生成からチーム横断テスト文化の醸成まで

<!-- .claude/CLAUDE.md -->
## BDD シナリオ生成ガイドライン
 
新機能を実装するとき、または既存機能を変更するときは、
必ず以下の手順で BDD シナリオを先に作成すること。
 
### Gherkin 記述ルール
- Feature の説明には「背景にある価値」を1文で記述する
- Scenario タイトルは「条件」から「結果」が明確になるように書く
- Given/When/Then は1行ずつ、1つの動作のみを記述する
- データテーブルや Examples を活用してシナリオを簡潔にする
- ビジネス用語を使い、技術的な実装詳細は含めない
 
### 生成コマンド
- `bdd generate <機能名>` でシナリオを生成
- `bdd steps <feature ファイル>` でステップ定義を生成
- `bdd review` で既存シナリオの品質レビュー

// steps/cart/cart.steps.ts
// Claude Code が自動生成したステップ定義（エラーハンドリング付き）
 
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
import type { CustomWorld } from '../support/world';
 
Given('カートが空である', async function(this: CustomWorld) {
  // カートをクリアするAPIを呼び出す
  const response = await this.page.request.post('/api/cart/clear', {
    headers: { Authorization: `Bearer ${this.authToken}` }
  });
  
  if (!response.ok()) {
    throw new Error(`カートのクリアに失敗: ${response.status()} ${await response.text()}`);
  }
  
  // カートページを開いて空であることを確認
  await this.page.goto('/cart');
  await expect(this.page.getByTestId('cart-empty-message')).toBeVisible();
});
 
When('商品 {string} の商品ページを開く', async function(this: CustomWorld, productName: string) {
  // 商品名から商品ページURLを検索して遷移
  await this.page.goto('/products');
  
  const productLink = this.page.getByRole('link', { name: productName });
  await expect(productLink).toBeVisible({ timeout: 5000 });
  await productLink.click();
  
  // ページ遷移完了を待機
  await this.page.waitForLoadState('networkidle');
  this.currentProductName = productName;
});
 
When('「カートに追加」ボタンをクリックする', async function(this: CustomWorld) {
  const addToCartButton = this.page.getByRole('button', { name: 'カートに追加' });
  
  await expect(addToCartButton).toBeEnabled({ timeout: 3000 });
  await addToCartButton.click();
  
  // 追加完了の確認（トースト通知や数量更新を待つ）
  await this.page.waitForResponse(
    response => response.url().includes('/api/cart') && response.status() === 200,
    { timeout: 5000 }
  );
});
 
Then('カートのアイコンに数字 {string} が表示される', async function(this: CustomWorld, count: string) {
  const cartBadge = this.page.getByTestId('cart-badge');
  await expect(cartBadge).toBeVisible();
  await expect(cartBadge).toHaveText(count);
});
 
When('以下の商品をカートに追加する:', async function(this: CustomWorld, dataTable: any) {
  const items = dataTable.hashes();
  
  for (const item of items) {
    const qty = parseInt(item['数量']);
    if (qty === 0) continue; // 数量が0の場合はスキップ
    
    // 商品ページへ遷移
    await this.page.goto('/products');
    const productLink = this.page.getByRole('link', { name: item['商品名'] });
    await productLink.click();
    await this.page.waitForLoadState('networkidle');
    
    // 数量を設定
    if (qty > 1) {
      const qtyInput = this.page.getByRole('spinbutton', { name: '数量' });
      await qtyInput.fill(String(qty));
    }
    
    // カートに追加
    await this.page.getByRole('button', { name: 'カートに追加' }).click();
    await this.page.waitForResponse(
      response => response.url().includes('/api/cart') && response.status() === 200,
      { timeout: 5000 }
    );
  }
});
 
Then('カートの合計金額が {int} 円と表示される', async function(this: CustomWorld, expectedPrice: number) {
  await this.page.goto('/cart');
  
  const totalElement = this.page.getByTestId('cart-total-price');
  await expect(totalElement).toBeVisible();
  
  // 表示価格の数値を抽出して比較
  const priceText = await totalElement.textContent();
  const actualPrice = parseInt(priceText?.replace(/[^0-9]/g, '') || '0');
  
  expect(actualPrice).toBe(expectedPrice);
});

// features/support/world.ts
import { World, IWorldOptions, setWorldConstructor } from '@cucumber/cucumber';
import { Browser, BrowserContext, Page, chromium } from '@playwright/test';
 
export interface CustomWorld extends World {
  browser: Browser;
  context: BrowserContext;
  page: Page;
  authToken: string;
  currentProductName?: string;
  testData: Record<string, any>;
}
 
class PlaywrightWorld extends World implements CustomWorld {
  browser!: Browser;
  context!: BrowserContext;
  page!: Page;
  authToken: string = '';
  currentProductName?: string;
  testData: Record<string, any> = {};
 
  constructor(options: IWorldOptions) {
    super(options);
  }
}
 
// フック設定（Before/After）
import { Before, After, BeforeAll, AfterAll } from '@cucumber/cucumber';
 
let sharedBrowser: Browser;
 
BeforeAll(async function() {
  sharedBrowser = await chromium.launch({
    headless: process.env.HEADED !== 'true',
    slowMo: process.env.SLOW_MO ? parseInt(process.env.SLOW_MO) : 0,
  });
});
 
AfterAll(async function() {
  await sharedBrowser?.close();
});
 
Before(async function(this: CustomWorld) {
  // テストごとに独立したコンテキストを作成（Cookie・ストレージが隔離される）
  this.context = await sharedBrowser.newContext({
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    viewport: { width: 1280, height: 720 },
    locale: 'ja-JP',
  });
  this.page = await this.context.newPage();
  
  // コンソールエラーをテストログに記録
  this.page.on('console', (msg) => {
    if (msg.type() === 'error') {
      console.error(`Browser Console Error: ${msg.text()}`);
    }
  });
});
 
After(async function(this: CustomWorld, scenario) {
  // テスト失敗時のスクリーンショット保存
  if (scenario.result?.status === 'FAILED') {
    const screenshotPath = `reports/screenshots/${scenario.pickle.name.replace(/\s/g, '_')}.png`;
    await this.page.screenshot({ path: screenshotPath, fullPage: true });
    this.attach(await this.page.screenshot(), 'image/png');
  }
  
  await this.context?.close();
});
 
setWorldConstructor(PlaywrightWorld);

# .github/workflows/bdd-tests.yml
name: BDD Tests
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  bdd-test:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: test_db
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
 
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright browsers
        run: npx playwright install chromium
      
      - name: Build application
        run: npm run build
        env:
          DATABASE_URL: postgresql://postgres:testpassword@localhost:5432/test_db
      
      - name: Run database migrations
        run: npm run db:migrate
        env:
          DATABASE_URL: postgresql://postgres:testpassword@localhost:5432/test_db
      
      - name: Start application
        run: npm start &
        env:
          DATABASE_URL: postgresql://postgres:testpassword@localhost:5432/test_db
          PORT: 3000
      
      - name: Wait for application startup
        run: npx wait-on http://localhost:3000 --timeout 30000
      
      - name: Run BDD tests
        run: npx cucumber-js
        env:
          BASE_URL: http://localhost:3000
      
      - name: Upload test reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: cucumber-reports
          path: reports/
          retention-days: 14
      
      - name: Upload failure screenshots
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: failure-screenshots
          path: reports/screenshots/

# .claude/commands/bdd-pr.md
# PR作成前にBDDシナリオを確認・更新するコマンド
 
1. 変更された機能に関連する .feature ファイルを特定する
2. 既存シナリオが変更後の仕様を反映しているか確認する
3. 不足しているシナリオを追加生成する
4. ステップ定義を更新する
5. テストをローカルで実行して通過を確認する
6. PR の説明文に追加・変更したシナリオを記載する

# ❌ 技術的すぎるシナリオ（避けるべき）
When ユーザーが POST /api/auth/login にリクエストを送信する
And レスポンスが 200 OK で JWT トークンを返す
 
# ✅ ビジネス観点のシナリオ
When ユーザーが正しいメールアドレスとパスワードを入力してログインする
Then ダッシュボードが表示される

// ❌ フレーキーになりやすい実装
await this.page.click('[data-testid="submit-button"]');
await this.page.waitForTimeout(1000); // 固定待機は禁物
 
// ✅ イベント駆動の待機
await Promise.all([
  this.page.waitForResponse(
    response => response.url().includes('/api/') && response.status() < 400
  ),
  this.page.click('[data-testid="submit-button"]')
]);
 
// ✅ ネットワークアイドル状態の待機
await this.page.click('[data-testid="submit-button"]');
await this.page.waitForLoadState('networkidle', { timeout: 10000 });

# Claude Code へのレビュー依頼コマンド例
# .claude/commands/bdd-review.md
 
## BDD シナリオ品質レビュー
 
以下の観点で features/ ディレクトリ全体をレビューしてください：
 
1. シナリオが技術的な実装詳細を含んでいないか
2. Background に過剰な前提条件が詰め込まれていないか  
3. 同じステップが複数のシナリオで繰り返されていないか（共通化の余地）
4. エッジケース（境界値・エラーケース）が不足していないか
5. シナリオ名が「条件 → 結果」の形式で書かれているか
6. 1つのシナリオが複数の振る舞いを検証していないか（単一責任）
 
改善提案はシナリオの書き換え案とともに提示してください。

@smoke @auth
Scenario: 正しい認証情報でログインが成功する
  ...
 
@regression @cart
Scenario: 在庫不足の場合にエラーが表示される
  ...