35BDD with Cucumber

35.1 What BDD really is

Behaviour-Driven Development: a collaboration technique where business, developers and testers agree on behaviour using a shared, near-English vocabulary before writing code. The artifact (a .feature file) doubles as both the spec and the automated test.

BDD is NOT just "writing tests in Gherkin". If your business doesn't read or contribute to the .feature files, you're getting all the syntax overhead and none of the collaboration benefit — use plain code tests instead.

35.2 Gherkin syntax

Feature: User authentication
  As a registered user
  I want to sign in to my account
  So that I can access my dashboard

  Background:
    Given the system has a user "alice@test.com" with password "secret"

  @smoke @auth
  Scenario: Successful sign-in
    Given I am on the sign-in page
    When  I enter "alice@test.com" and "secret"
    And   I click "Sign in"
    Then  I should see "Welcome, Alice"
    And   I should be on the dashboard

  Scenario: Wrong password
    Given I am on the sign-in page
    When  I enter "alice@test.com" and "wrong"
    And   I click "Sign in"
    Then  I should see an error "Invalid credentials"
    And   I should remain on the sign-in page

  Scenario Outline: Account lockout after <attempts> bad attempts
    Given I am on the sign-in page
    When  I attempt to sign in <attempts> times with wrong password
    Then  the account should be <state>

    Examples:
      | attempts | state    |
      | 3        | active   |
      | 5        | locked   |
      | 10       | locked   |

Keywords

35.3 Step definitions in TS

npm i -D @cucumber/cucumber @playwright/test

// steps/auth.steps.ts
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
import { World } from '../world';   // custom World (see below)

Given('the system has a user {string} with password {string}',
  async function (this: World, email: string, password: string) {
    await this.api.post('/test/users', { data: { email, password } });
  });

Given('I am on the sign-in page', async function (this: World) {
  await this.page.goto('/login');
});

When('I enter {string} and {string}',
  async function (this: World, email: string, password: string) {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
  });

When('I click {string}', async function (this: World, label: string) {
  await this.page.getByRole('button', { name: label }).click();
});

Then('I should see {string}', async function (this: World, text: string) {
  await expect(this.page.getByText(text)).toBeVisible();
});

35.4 The "World" — per-scenario context

// world.ts
import { setWorldConstructor, World as CW } from '@cucumber/cucumber';
import { Browser, BrowserContext, Page, chromium, APIRequestContext, request } from 'playwright';

export class World extends CW {
  browser!: Browser; context!: BrowserContext; page!: Page; api!: APIRequestContext;

  async open() {
    this.browser = await chromium.launch();
    this.context = await this.browser.newContext();
    this.page = await this.context.newPage();
    this.api = await request.newContext({ baseURL: 'https://api.example.com' });
  }
  async close() {
    await this.api.dispose();
    await this.context.close();
    await this.browser.close();
  }
}
setWorldConstructor(World);

35.5 Hooks

// hooks.ts
import { Before, After, BeforeAll, AfterAll, Status } from '@cucumber/cucumber';
import { World } from './world';

BeforeAll(async () => { /* one-time global setup */ });
AfterAll(async () => { /* one-time global teardown */ });

Before(async function (this: World, scenario) { await this.open(); });

After(async function (this: World, scenario) {
  if (scenario.result?.status === Status.FAILED) {
    const buf = await this.page.screenshot();
    this.attach(buf, 'image/png');
  }
  await this.close();
});

35.6 Tags & selective runs

npx cucumber-js --tags "@smoke and not @wip"
npx cucumber-js --tags "@auth or @checkout"
npx cucumber-js features/auth.feature

35.7 Reports

// cucumber.json (config)
{
  "default": {
    "paths": ["features/**/*.feature"],
    "require": ["steps/**/*.ts", "hooks.ts", "world.ts"],
    "requireModule": ["ts-node/register"],
    "format": ["progress-bar", "html:reports/cucumber.html", "json:reports/cucumber.json"]
  }
}

The HTML report is shareable with non-tech stakeholders — one of the few real BDD wins.

35.8 Common BDD anti-patterns

• Imperative Gherkin — "When I click the button with id btn-pri" leaks implementation. Use declarative — "When I submit the form".
• Bloated Background — runs before every scenario. Keep it small and necessary.
• Step explosion — every feature defines new When I do X steps that look similar. Refactor common verbs.
• Over-abstracted steps — When I do the thing tells nobody anything. Stay readable.
• Gherkin without business — if business never reads it, you're paying syntax tax for no payoff.
• Scenario as full workflow — 20-step scenarios collapse. Keep scenarios atomic; one observation per scenario.

35.9 When NOT to use Cucumber