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

Two Things That Break Quietly in cucumber.config.ts (measured on v13.2.1)

That config file differs from the one this article used to show. When I actually ran it, two parts turned out not to behave the way the code implied. It seems worth documenting exactly what happened.

First: defineConfig is not exported by @cucumber/cucumber

If you're used to Vite or Playwright config files, you reach for defineConfig by reflex. But @cucumber/cucumber 13.2.1 has no export by that name.

$ node -e "const c = require('@cucumber/cucumber'); console.log(typeof c.defineConfig)"
undefined

Call it anyway and you get exactly what you'd expect:

TypeError: defineConfig is not a function

A plain object as the default export is the correct form. TypeScript looks like it should catch this early, but depending on your setup the import itself resolves fine, and you only find out at runtime.

Second: timeout in the config file is silently ignored

This one was more troublesome, precisely because nothing fails.

Working as an indie developer, where I am my own only reviewer, this "silently ignored" class of bug is the one I fear most. Nobody flags it, and you can run for weeks believing a setting is in effect when it never was.

The keys Cucumber v13 accepts are enumerated in the package's own DEFAULT_CONFIGURATION — backtrace, dryRun, format, formatOptions, parallel, require, requireModule, retry, strict, tags, worldParameters, and so on. timeout is not among them. Write it anyway and it's discarded without so much as a warning.

Here's a single step that takes 6 seconds, run with timeout: 30000 present in the config file:

$ npx cucumber-js --import steps/x.mjs features/x.feature
F

Failed scenarios:
  1) noop # features/x.feature:2
       Given nothing # steps/x.mjs:2
           Error: function timed out, ensure the promise resolves within 5000 milliseconds

1 scenario (1 failed)
1 step (1 failed)
0m 5.16s

The intent was 30 seconds; the actual limit was the built-in 5000ms. Leave the step untouched and call setDefaultTimeout(30000) in a support file instead, and it passes:

$ npx cucumber-js --import steps/x.mjs features/x.feature
.

1 scenario (1 passed)
1 step (1 passed)
0m 6.15s (0m 6.7s executing your code)

In BDD that drives a real browser, 5 seconds runs out quickly. Spending days chasing a test that only fails in CI, and finding that the cause was a timeout the config parser never read, is a detour worth avoiding. Set timeouts in the World support file described below.

Both traps apply equally when you have Claude Code write the config for you. Configuration syntax that was correct in one major version quietly stops being correct in the next, and generated code carries that history with it. Rather than generating and committing straight away, I keep one minimal .feature around and treat "npx cucumber-js goes green" as part of the same task. A few minutes there saves hours later.

Auto-Generating Gherkin Scenarios with Claude Code

This is where Claude Code really earns its keep. Pass requirements documents or user stories to Claude Code, and it generates BDD-appropriate scenarios automatically.

Writing BDD Guidelines in CLAUDE.md

<!-- .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

A sample Claude Code session for scenario generation:

# Example Claude Code interaction
You: Generate BDD scenarios for a shopping cart feature.
     Requirements: add/remove items, change quantity, calculate total price.

Claude Code: [Generates features/cart/cart.feature]

Feature: Shopping Cart
  Value: Users can temporarily store desired products and review the total price

  Background:
    Given the user is logged in
    And product "Wireless Earbuds Pro" is in stock with quantity 10 at price $128.00
    And product "USB Cable" is in stock with quantity 50 at price $8.80

  Scenario: Adding a product to the cart
    When the user opens the product page for "Wireless Earbuds Pro"
    And they click the "Add to Cart" button
    Then the cart icon shows the number "1"
    And opening the cart page shows 1 "Wireless Earbuds Pro"
    And the cart total shows $128.00

  Scenario: Changing the quantity of a cart item
    Given "Wireless Earbuds Pro" is in the cart with quantity 1
    When they change the quantity to "3"
    Then the cart total shows $384.00

  Scenario Outline: Adding multiple products to the cart
    Given the cart is empty
    When they add the following products to the cart:
      | Product Name            | Qty    |
      | Wireless Earbuds Pro    | <qty1> |
      | USB Cable               | <qty2> |
    Then the cart total shows $<expected>

    Examples:
      | qty1 | qty2 | expected |
      | 1    | 1    | 136.80   |
      | 2    | 3    | 282.40   |
      | 0    | 5    | 44.00    |

  Scenario: Error is shown when quantity exceeds stock
    Given "Wireless Earbuds Pro" is in the cart with quantity 9
    When they try to change the quantity to "11"
    Then the error message "Cannot exceed available stock (Available: 10)" is displayed
    And the cart quantity remains at 9

Writing exhaustive scenarios like these manually is extremely difficult, but when you delegate to Claude Code, edge cases you'd typically overlook — insufficient stock, zero quantities, etc. — are naturally included.

Auto-Generating Step Definitions

Once scenarios are in place, step definitions come next. Pass the .feature file to Claude Code and it generates TypeScript step definitions automatically.

// 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 '../../features/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);
});

One thing commonly overlooked in step definitions is error handling. When you let Claude Code generate them, it naturally includes waitForResponse, timeout settings, and explicit error messages — the parts I tend to skip when writing by hand. Claude Code implements them faithfully.

Designing the World Object

Cucumber's World is the mechanism for sharing state between steps. Designing it well dramatically improves test readability and reusability.

// features/support/world.ts
import { World, IWorldOptions, setWorldConstructor, setDefaultTimeout } from '@cucumber/cucumber';
import { Browser, BrowserContext, Page, chromium } from '@playwright/test';
 
// The config file's timeout is ignored, so override the default here (default: 5000ms)
setDefaultTimeout(30000);
 
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);

Integrating with CI/CD Pipelines

Here's a GitHub Actions setup for running BDD tests automatically:

# .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/

Common Pitfalls and How to Handle Them

Here are four places where BDD adoption typically goes wrong.

1. Scenarios become too technical

# ❌ 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

Claude Code can generate implementation-heavy scenarios if you don't explicitly tell it to use a business perspective. Make your writing rules clear in CLAUDE.md.

2. Background sections become bloated

When the Background section contains 10+ lines of preconditions, readability drops sharply. Asking Claude Code to "refactor this Background to three lines or fewer" typically produces a proposal to extract test data into fixtures.

3. Inconsistent step granularity

Writing "Login" as one step in some scenarios and three steps in others makes maintenance painful. Organizing shared steps in a common/ folder and periodically asking Claude Code to "identify what can be extracted as shared steps" is an effective practice.

4. Dealing with flaky tests

In modern web apps with heavy async processing, timing-dependent test failures are common. Here's the pattern Claude Code recommends:

// ❌ 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"]')
]);
 
// ✅ Wait for the state itself (web-first assertion)
await this.page.getByTestId('submit-button').click();
await expect(this.page.getByTestId('success-message')).toBeVisible();

This article used to recommend waitForLoadState('networkidle') as a waiting strategy. Current Playwright (verified on 1.62.1) marks it DISCOURAGED right in the type definitions, with the note: "Don't use this method for testing, rely on web assertions to assess readiness instead." The 500ms-of-silence condition may never be satisfied in an app that polls or carries analytics tags, which makes it a source of flakiness rather than a cure for it. What you want to wait for is the state you expect on screen, not quiet on the network.

Enabling Non-Engineers to Participate

The original purpose of BDD is for engineers and business stakeholders to share the same scenarios as a common language. Here's a workflow that enables non-engineers using Claude Code.

Scenario Creation Flow for POs and Product Teams

1. Have them write requirements in bullet points (natural language is fine)
2. Use Claude Code to convert to Gherkin
3. Have the PO review and revise (they shouldn't need to touch the technical parts)
4. Engineers implement the step definitions

# Requirements written by PO (natural language)
"Users should be able to change their profile photo.
Only JPEG and PNG formats. Under 5MB. Changes reflected immediately."

# Gherkin generated by Claude Code
Feature: Profile Photo Update

  Scenario: Profile photo changes successfully with a valid image
    Given the user is on the profile settings page
    When they upload a 2MB JPEG file
    Then the profile photo updates to the new image
    And the change is immediately reflected in the header icon

  Scenario: Images over 5MB cannot be uploaded
    Given the user is on the profile settings page
    When they try to upload a 6MB PNG file
    Then the error message "File size must be 5MB or less" is displayed
    And the profile photo is not changed

  Scenario: Unsupported file formats cannot be uploaded
    Given the user is on the profile settings page
    When they try to upload a GIF file
    Then the error message "Please select a JPEG or PNG file" is displayed

The key here is maintaining a state where POs can read and modify scenarios. Keeping implementation details out of scenarios — which you can explicitly instruct Claude Code to do — makes it much easier for non-engineers to understand what's being tested.

Periodic Quality Reviews with Claude Code

Running periodic quality checks on existing scenarios prevents drift and bloat:

# 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.

Long-Term Tips for Sustaining BDD

A few things that help BDD stick over time.

Manage test execution time: As scenarios multiply, execution time grows. Tagging scenarios with @smoke, @regression, and @critical — then running only smoke tests per PR and full regression on a schedule — is a practical approach.

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

Don't let scenario debt accumulate: Deferring scenario updates during feature changes quickly creates drift from reality. Including "update related scenarios" as a PR merge requirement keeps scenarios accurate.

Set performance targets: In my projects, I aim for smoke tests to finish within 3 minutes and full regression within 20 minutes. When those thresholds look threatened, it's the signal to revisit parallel execution settings.

Your First Step

BDD isn't about "building the framework and calling it done" — it's something a team grows together over time. The best starting point is writing a single scenario for the feature you're currently working on. Just ask Claude Code "please write a Gherkin scenario for this feature" and you'll get a solid result to start from.

Step definitions, CI integration — all of that can come later. The first step is simply getting a scenario to exist. Five minutes is enough to get started. Give it a try in your current project today.

If nothing else, I hope the two measured findings added to this article stay with you. defineConfig doesn't exist, and timeout in the config file isn't read. Don't take generated code on trust — run it once in the smallest possible setup. That habit, more than any framework choice, seems to decide whether a team keeps BDD alive.

For the execution environment itself and for dealing with flakiness, see Running Claude Code × Playwright E2E Tests in Production and Eliminating Flaky Tests Systematically with Claude Code. If you want this running as a gate in CI, Running Claude Code Hooks as a Quality Gate Without Breaking Your Pipeline covers that side.

Thank you for reading this far. I'm still working things out myself, so if you notice something once you put this into practice, I'd genuinely welcome hearing about it.