BDD with Claude Code in Production— From Gherkin Scenario Generation to Cross-Team Test Culture

<!-- .claude/CLAUDE.md -->
## BDD Scenario Generation Guidelines
 
When implementing new features or modifying existing ones,
always create BDD scenarios first using the following process.
 
### Gherkin Writing Rules
- Feature descriptions must include a one-sentence "underlying value"
- Scenario titles should make the condition and outcome immediately clear
- Each Given/When/Then step should describe only one action per line
- Use data tables and Examples to keep scenarios concise
- Use business terminology — never include technical implementation details
 
### Generation Commands
- `bdd generate <feature-name>` to generate scenarios
- `bdd steps <feature-file>` to generate step definitions
- `bdd review` for quality review of existing scenarios

// steps/cart/cart.steps.ts
// Auto-generated step definitions by Claude Code (with error handling)
 
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
import type { CustomWorld } from '../support/world';
 
Given('the cart is empty', async function(this: CustomWorld) {
  // Clear the cart via API
  const response = await this.page.request.post('/api/cart/clear', {
    headers: { Authorization: `Bearer ${this.authToken}` }
  });
  
  if (!response.ok()) {
    throw new Error(`Failed to clear cart: ${response.status()} ${await response.text()}`);
  }
  
  // Navigate to cart page and verify it's empty
  await this.page.goto('/cart');
  await expect(this.page.getByTestId('cart-empty-message')).toBeVisible();
});
 
When('the user opens the product page for {string}', async function(this: CustomWorld, productName: string) {
  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('they click the {string} button', async function(this: CustomWorld, buttonText: string) {
  const button = this.page.getByRole('button', { name: buttonText });
  
  await expect(button).toBeEnabled({ timeout: 3000 });
  await button.click();
  
  // Wait for the cart API response
  await this.page.waitForResponse(
    response => response.url().includes('/api/cart') && response.status() === 200,
    { timeout: 5000 }
  );
});
 
Then('the cart icon shows the number {string}', async function(this: CustomWorld, count: string) {
  const cartBadge = this.page.getByTestId('cart-badge');
  await expect(cartBadge).toBeVisible();
  await expect(cartBadge).toHaveText(count);
});
 
When('they add the following products to the cart:', async function(this: CustomWorld, dataTable: any) {
  const items = dataTable.hashes();
  
  for (const item of items) {
    const qty = parseInt(item['Qty']);
    if (qty === 0) continue;
    
    await this.page.goto('/products');
    const productLink = this.page.getByRole('link', { name: item['Product Name'] });
    await productLink.click();
    await this.page.waitForLoadState('networkidle');
    
    if (qty > 1) {
      const qtyInput = this.page.getByRole('spinbutton', { name: 'Quantity' });
      await qtyInput.fill(String(qty));
    }
    
    await this.page.getByRole('button', { name: 'Add to Cart' }).click();
    await this.page.waitForResponse(
      response => response.url().includes('/api/cart') && response.status() === 200,
      { timeout: 5000 }
    );
  }
});
 
Then('the cart total shows ${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 = parseFloat(priceText?.replace(/[^0-9.]/g, '') || '0');
  
  expect(actualPrice).toBeCloseTo(expectedPrice, 2);
});

// 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);
  }
}
 
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) {
  // Create an isolated context per test (cookies and storage are separate)
  this.context = await sharedBrowser.newContext({
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    viewport: { width: 1280, height: 720 },
    locale: 'en-US',
  });
  this.page = await this.context.newPage();
  
  // Log browser console errors
  this.page.on('console', (msg) => {
    if (msg.type() === 'error') {
      console.error(`Browser Console Error: ${msg.text()}`);
    }
  });
});
 
After(async function(this: CustomWorld, scenario) {
  // Save screenshot on test failure
  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/

# ❌ Too technical (avoid this)
When the user sends a POST request to /api/auth/login
And the response returns 200 OK with a JWT token
 
# ✅ Business-oriented scenario
When the user enters valid credentials and clicks Login
Then the dashboard is displayed

// ❌ Prone to flakiness
await this.page.click('[data-testid="submit-button"]');
await this.page.waitForTimeout(1000); // Fixed waits are fragile
 
// ✅ Event-driven waiting
await Promise.all([
  this.page.waitForResponse(
    response => response.url().includes('/api/') && response.status() < 400
  ),
  this.page.click('[data-testid="submit-button"]')
]);
 
// ✅ Network idle state
await this.page.click('[data-testid="submit-button"]');
await this.page.waitForLoadState('networkidle', { timeout: 10000 });

# Example Claude Code review command
# .claude/commands/bdd-review.md
 
## BDD Scenario Quality Review
 
Please review the entire features/ directory with the following criteria:
 
1. Do any scenarios contain technical implementation details?
2. Are any Background sections overloaded with preconditions?
3. Are there repeated steps across multiple scenarios? (consolidation opportunity)
4. Are there missing edge cases? (boundary values, error cases)
5. Are scenario names written in the "condition → outcome" format?
6. Is any single scenario testing more than one behavior? (single responsibility)
 
Present improvement suggestions with rewritten scenario examples.

@smoke @auth
Scenario: Login succeeds with valid credentials
  ...
 
@regression @cart
Scenario: Error is shown when quantity exceeds stock
  ...