Cucumber & BDD,
done properly.

# the three packages that make a Cucumber + Playwright project
npm init -y
npm i -D @cucumber/cucumber @playwright/test typescript ts-node
npx playwright install

# a comment — Cucumber ignores this line
@cart @regression
Feature: Shopping cart
  As a shopper
  I want to manage items in my cart
  So that I can buy what I need

  Background:
    Given the user is logged in as "standard_user"
    And the cart is empty

  @smoke
  Scenario: Add a single item
    When the user adds "Sauce Labs Backpack" to the cart
    Then the cart badge should show 1

  Scenario: Add several items from a table
    When the user adds the following items:
      | item                  | qty |
      | Sauce Labs Backpack   | 1   |
      | Sauce Labs Bike Light | 2   |
    Then the cart badge should show 3

  Scenario Outline: Removing items updates the badge
    Given the cart contains <start> items
    When the user removes <removed> items
    Then the cart badge should show <left>

    Examples:
      | start | removed | left |
      | 3     | 1       | 2    |
      | 2     | 2       | 0    |

  Scenario: Checkout shows a confirmation message
    Given the cart contains 1 item
    When the user completes checkout
    Then the confirmation message should read:
      """
      Thank you for your order!
      Your order has been dispatched.
      """

Feature: Secure area login
  As a registered user
  I want to log in with valid credentials
  So that I can reach the secure area

  Background:
    Given the user is on the login page

  @smoke
  Scenario: Successful login
    When the user logs in as "tomsmith" with password "SuperSecretPassword!"
    Then the secure area should be displayed
    And the message "You logged into a secure area!" should be shown

  @regression
  Scenario Outline: Login is rejected for bad credentials
    When the user logs in as "<username>" with password "<password>"
    Then the error "<message>" should be shown

    Examples:
      | username | password             | message                   |
      | wrong    | SuperSecretPassword! | Your username is invalid! |
      | tomsmith | wrong                | Your password is invalid! |

import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';

Given('the user is on the login page', async function () {
  await this.page.goto('https://the-internet.herokuapp.com/login');
});

When('the user logs in as {string} with password {string}',
  async function (username: string, password: string) {
    await this.page.fill('#username', username);
    await this.page.fill('#password', password);
    await this.page.click('button[type="submit"]');
  });

Then('the secure area should be displayed', async function () {
  await expect(this.page).toHaveURL(/secure/);
});

Then('the message {string} should be shown', async function (text: string) {
  await expect(this.page.locator('#flash')).toContainText(text);
});

Then('the error {string} should be shown', async function (text: string) {
  await expect(this.page.locator('#flash')).toContainText(text);
});

// captures a number — note the {int}, and Then receives it as a number
Then('the cart badge should show {int}', async function (count: number) {
  await expect(this.page.locator('.cart-badge')).toHaveText(String(count));
});

// optional 's' and a captured word, all in one readable line
Given('I have {int} item(s) of type {word}', async function (n: number, type: string) {
  // matches "I have 1 item of type book" AND "I have 3 items of type pen"
});

When(/^the user adds "(.+)" to the cart$/, async function (item: string) {
  await this.page.getByRole('button', { name: `Add ${item}` }).click();
});

import { defineParameterType } from '@cucumber/cucumber';

defineParameterType({
  name: 'priority',
  regexp: /low|medium|high/,
  transformer: (s) => s as 'low' | 'medium' | 'high',
});

// now usable anywhere:
// When('I create a {priority} bug', async function (priority) { ... })
//   matches: When I create a high bug

import { When, Then, DataTable } from '@cucumber/cucumber';
import { expect } from '@playwright/test';

When('the user adds the following items:', async function (table: DataTable) {
  // .hashes() → [{ item: 'Sauce Labs Backpack', qty: '1' }, ...]
  for (const row of table.hashes()) {
    const qty = Number(row.qty);
    for (let i = 0; i < qty; i++) {
      await this.page.getByRole('button', { name: `Add ${row.item}` }).click();
    }
  }
});

Then('the confirmation message should read:', async function (docString: string) {
  await expect(this.page.locator('#message')).toContainText(docString.trim());
});

import { setWorldConstructor, World, IWorldOptions } from '@cucumber/cucumber';
import { Browser, BrowserContext, Page } from '@playwright/test';

export class CustomWorld extends World {
  browser!: Browser;
  context!: BrowserContext;
  page!: Page;

  constructor(options: IWorldOptions) {
    super(options);
  }
}

setWorldConstructor(CustomWorld);

import { BeforeAll, Before, After, AfterAll, setDefaultTimeout } from '@cucumber/cucumber';
import { chromium, Browser } from '@playwright/test';
import { CustomWorld } from './world';

setDefaultTimeout(30 * 1000); // 30s per step

let browser: Browser;

BeforeAll(async function () {
  browser = await chromium.launch({ headless: true });
});

Before(async function (this: CustomWorld) {
  this.context = await browser.newContext();
  this.page = await this.context.newPage(); // ← this is the this.page your steps use
});

After(async function (this: CustomWorld) {
  await this.page?.close();
  await this.context?.close();
});

AfterAll(async function () {
  await browser?.close();
});

  Scenario Outline: Login outcomes
    When the user logs in as "<username>" with password "<password>"
    Then the page should show "<result>"

    @valid
    Examples: Accepted
      | username | password             | result      |
      | tomsmith | SuperSecretPassword! | Secure Area |

    @invalid
    Examples: Rejected
      | username | password | result                    |
      | wrong    | nope     | Your username is invalid! |
      | tomsmith | nope     | Your password is invalid! |

my-bdd-suite/
├─ features/
│  ├─ login.feature          # the scenarios — Gherkin (the WHAT)
│  ├─ cart.feature
│  ├─ steps/                 # step definitions — the glue (the HOW)
│  │  ├─ login.steps.ts
│  │  └─ cart.steps.ts
│  └─ support/               # World, hooks, params (the PLUMBING)
│     ├─ world.ts
│     ├─ hooks.ts
│     └─ parameters.ts
├─ cucumber.js               # Cucumber config + named profiles
├─ tsconfig.json
└─ package.json

module.exports = {
  default: {
    requireModule: ['ts-node/register'],                 // run TypeScript directly
    require: ['features/support/**/*.ts', 'features/steps/**/*.ts'],
    paths: ['features/**/*.feature'],
    format: [
      'progress-bar',                                    // live console output
      'html:reports/cucumber.html',                      // shareable HTML report
      'json:reports/cucumber.json',                      // machine-readable results
    ],
    formatOptions: { snippetInterface: 'async-await' },
    publishQuiet: true,
  },
  smoke: {
    requireModule: ['ts-node/register'],
    require: ['features/support/**/*.ts', 'features/steps/**/*.ts'],
    paths: ['features/**/*.feature'],
    tags: '@smoke',                                       // only the smoke set
  },
};

{
  "scripts": {
    "test": "cucumber-js",
    "test:smoke": "cucumber-js --profile smoke",
    "test:headed": "HEADLESS=false cucumber-js",
    "report": "open reports/cucumber.html"
  }
}

# run everything
npx cucumber-js

# run one feature, or one scenario by line number
npx cucumber-js features/login.feature
npx cucumber-js features/login.feature:12

# filter by tags — boolean logic is supported
npx cucumber-js --tags '@smoke'
npx cucumber-js --tags '@regression and not @wip'

# use a saved profile from cucumber.js
npx cucumber-js --profile smoke

# check the glue WITHOUT launching the app — finds undefined/ambiguous steps
npx cucumber-js --dry-run

# stop on the first failure
npx cucumber-js --fail-fast

# auto-retry flaky scenarios up to 2 times
npx cucumber-js --retry 2 --retry-tag-filter '@flaky'

# run scenarios in parallel across 4 workers
npx cucumber-js --parallel 4

import { Before, After } from '@cucumber/cucumber';
import { request } from '@playwright/test';
// extend CustomWorld with:  api!: APIRequestContext;  response!: APIResponse;

Before({ tags: '@api' }, async function () {
  this.api = await request.newContext({ baseURL: 'https://reqres.in' });
});

After({ tags: '@api' }, async function () {
  await this.api?.dispose();
});

@api
Feature: Users API
  As a developer
  I want the users endpoint to behave correctly
  So that clients can rely on it

  Scenario: Fetch a single user
    When I GET "/api/users/2"
    Then the response status should be 200
    And the JSON field "data.id" should equal "2"

  Scenario: Create a user
    When I POST "/api/users" with body:
      """
      { "name": "neo", "job": "the one" }
      """
    Then the response status should be 201
    And the JSON field "name" should equal "neo"

import { When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';

When('I GET {string}', async function (path: string) {
  this.response = await this.api.get(path);
});

When('I POST {string} with body:', async function (path: string, body: string) {
  this.response = await this.api.post(path, { data: JSON.parse(body) });
});

Then('the response status should be {int}', async function (status: number) {
  expect(this.response.status()).toBe(status);
});

Then('the JSON field {string} should equal {string}',
  async function (path: string, expected: string) {
    const json = await this.response.json();
    const actual = path.split('.').reduce((o: any, k: string) => o?.[k], json);
    expect(String(actual)).toBe(expected);
  });

npx cucumber-js                          # run all
npx cucumber-js features/x.feature:12    # one scenario by line
npx cucumber-js --tags '@smoke and not @wip'
npx cucumber-js --profile smoke          # saved config
npx cucumber-js --dry-run                # find undefined steps
npx cucumber-js --fail-fast              # stop on first failure
npx cucumber-js --retry 2                # retry flaky scenarios
npx cucumber-js --parallel 4             # parallel workers

import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';

Given('a precondition', async function () { /* set state on this */ });
When('an action {string}', async function (arg: string) { /* do it */ });
Then('an outcome {int}', async function (n: number)  { /* assert */ });