How to Integrate Playwright With Cucumber

What Is Cucumber?

Cucumber is a testing library for Behavior Driven Development (BDD) that lets teams write tests in plain English. It reads human-readable descriptions of software behavior and runs matching code to check that the software behaves as described.

Behavior Driven Development (BDD) is a software development process that encourages collaboration between developers, QA, and non-technical stakeholders. Stakeholders can describe expected behavior without knowing how to write code, using a shared language called Gherkin.

What Is Gherkin?

Gherkin is a domain-specific language written in plain English that describes software behavior without specifying how it's implemented. The Gherkin reference defines its primary keywords, including Feature, Scenario, Given, When, Then, And, and But. For a deeper walkthrough of the syntax, see this guide to Gherkin testing.

Example of a Gherkin Feature File:

Feature: Perform Google Search
 As a user,
 I want to use Google to search for terms
 So that I can find relevant information quickly.
 Scenario: Execute a Search Using a Specific Keyword
   Given the user is on the Google homepage
   When the user enters "Playwright" into the search field
   Then the search results related to "Playwright" should be displayed

Breakdown of the Gherkin feature file:

• Feature - Describes the feature being tested. In this case, performing a Google search.
• Scenario - A specific use case under the feature. Here, it describes performing a search with a keyword.
• Given - Sets up the initial context. The user is on the Google homepage.
• When - Describes the action taken by the user. The user enters a search term.
• Then - Describes the expected result. The search results related to the keyword should be displayed.

The remaining keywords, And and But, chain extra steps onto the previous one: And adds another condition or outcome, while But adds a negative one, such as "But the error banner should not be displayed".

Note: Write your Playwright scenarios in Gherkin and run them across 3,000+ browser and OS combinations on the TestMu AI cloud grid. Try TestMu AI Today!

How to Set Up Playwright With Cucumber?

Before starting, check your Node.js version with node -v. The @cucumber/cucumber package manifest for version 13.2.1 declares Node.js 22, 24, or 26 and later; on Node.js 20.12 it fails at startup with an ERR_REQUIRE_ESM error.

• Install Playwright if it's not already installed on your system.
• Use any IDE; this guide uses VS Code.
• In VS Code, add the following extensions:
• Cucumber VS Code extension - A language server for Cucumber with auto-completion, "go to definition", and warnings for undefined steps.
• Cucumber (Gherkin) Full Support - Syntax highlighting, auto-completion, and snippets for Gherkin.

Setting Up Playwright

• Playwright provides a CLI tool to create a new project with a single command. You can use npm, yarn, or pnpm; this guide uses pnpm.

  Run the following command, replacing <project-name> with your preferred project name:

  pnpm create playwright playwright-cucumber

• Answer Playwright's setup questions:
• Do you want to use TypeScript or JavaScript? - This guide uses TypeScript.
• Where to put your end-to-end tests? - The default folder is tests. You can leave it as is.
• Add a GitHub Actions workflow file? - Choose yes if you want a starter CI workflow. The Playwright CI/CD guide covers pipeline setup in depth.
• Install Playwright browsers? - Choose yes, or run pnpm exec playwright install later.
• Playwright downloads the dependencies it needs and prints the commands you can use to run tests:

• Here is the project structure that Playwright creates:

.
└── playwright-cucumber
   ├── .github
   │   └── workflows
   │       └── playwright.yml
   ├── node_modules
   ├── tests
   │   └── example.spec.ts
   ├── tests-examples
   │   └── demo-todo-app.spec.ts
   ├── .gitignore
   ├── package.json
   ├── playwright.config.ts
   └── pnpm-lock.yaml

• The playwright.config.ts file configures Playwright Test. Cucumber-JS does not read it, so browser settings for the Cucumber suite live in the hooks you write later.

Setting Up Cucumber

• Install Cucumber to start writing tests in Gherkin:

pnpm add -D @cucumber/cucumber

• Install a TypeScript transpiler so Cucumber can load .ts step definitions. Older guides, including earlier versions of this one, use ts-node, but ts-node 10.9.2 is its latest release and crashes on load with TypeScript 7.0.2 ("Cannot read properties of undefined (reading 'fileExists')"). Use tsx instead:

pnpm add -D tsx

• Create a file called cucumber.js in the root of the project. Cucumber reads its configuration from this file, including the location of feature files and step definitions:

module.exports = {
  default: {
    paths: ['tests/features/'],
    requireModule: ['tsx/cjs'],
    require: ['tests/steps/**/*.ts'],
    format: ['progress'],
  },
};

In this configuration:

• paths points Cucumber at the feature files in tests/features/.
• requireModule loads tsx before any step file, so TypeScript compiles on the fly.
• require loads every step definition in tests/steps/.
• format sets the console output; the reports section adds a JSON formatter here.
• The default profile is picked up whenever pnpm exec cucumber-js or npx cucumber-js runs.

How to Write Tests Using Playwright With Cucumber?

A Playwright Cucumber test has three parts: a feature file with the scenario, a world file with hooks that own the browser, and step definitions that call Playwright. For conventions on keeping scenarios maintainable as the suite grows, see these Cucumber best practices.

Feature Files

Create a directory called features inside tests, then add a file named submit-form.feature:

└── playwright-cucumber
   ├── ...
   ├── tests/
   │   ├── features/  # Add this directory
   │   │   └── submit-form.feature  # Add this file
   │   └── ...
   └── ...

Write a feature that submits a form with a message:

Feature: Display a message when a form is submitted
  As a user,
  I want to submit a form with a message
  So that I can see the message displayed on the page.
Scenario: Submit a form with a message
  Given the user is on the form page
  When the user enters "Hello, World!" into the message field
  And the user clicks the submit button
  Then the message "Hello, World!" should be displayed on the page

The scenario breaks down into four steps:

• Given - The user is on the form page.
• When - The user enters "Hello, World!" into the message field.
• And - The user clicks the submit button.
• Then - The message "Hello, World!" should be displayed on the page.

The World Object in Cucumber

Cucumber creates a new World object for each scenario and binds it to this inside step definitions and hooks, which makes it the place for per-scenario state. Hooks defined next to it run code before and after each scenario.

Create a file called world.ts in the tests/steps directory:

└── playwright-cucumber
   ├── ...
   ├── tests/
   │   ├── steps/  # Add this directory
   │   │   └── world.ts  # Add this file
   │   └── ...
   └── ...

In world.ts, add a Before and an After hook that run around each scenario:

import { After, Before, setDefaultTimeout } from '@cucumber/cucumber';
import { Browser, Page, chromium } from '@playwright/test';
let page: Page;
let browser: Browser;
setDefaultTimeout(60000);
Before(async () => {
  browser = await chromium.launch();
  page = await browser.newPage();
});
After(async () => {
  await browser.close();
});
export { page, browser };

The Before hook launches Chromium and opens a new page; swap in firefox or webkit to test another engine. The After hook closes the browser, and setDefaultTimeout raises Cucumber's step timeout to 60 seconds.

The file exports page and browser so step definitions can import them. Because the exports are module-level variables, each Cucumber worker process gets its own copy when you later run with --parallel.

Setting a Custom World Object

To keep the page on the World instead of in module variables, register your own World class with setWorldConstructor:

import { setWorldConstructor, World, IWorldOptions } from '@cucumber/cucumber';
class CustomWorld extends World {
  customProp = "I'm a custom prop";
  constructor(options: IWorldOptions) {
    super(options);
  }
}
setWorldConstructor(CustomWorld);

Step definitions then read custom properties through this:

import { When } from '@cucumber/cucumber';
When('I do something', async function () {
  console.log(this.customProp);
});

To use this in step definitions, declare them with the function keyword; arrow functions do not bind the World. The rest of this tutorial uses the simpler module exports from world.ts.

Writing Step Definitions

Step definitions are the code that performs each action described in the feature file. To have Cucumber print snippet stubs for every undefined step without opening a browser, run a dry run:

pnpm exec cucumber-js --dry-run

Cucumber reads the feature files in tests/features, reports the four steps as undefined, and prints a stub for each. Copy them into a new file, tests/steps/submit-form.ts:

└── playwright-cucumber
   ├── ...
   ├── tests/
   │   ├── steps/
   │   │   └── submit-form.ts  # Add this file
   │   └── ...
   └── ...

Then fill each stub with Playwright calls against the Simple Form Demo on the TestMu AI Selenium Playground:

import { page } from './world';
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
Given('the user is on the form page', async function () {
  await page.goto('https://www.testmuai.com/selenium-playground/simple-form-demo/', { waitUntil: 'networkidle' });
});
When('the user enters {string} into the message field', async function (message: string) {
  await page.getByPlaceholder('Please enter your Message').fill(message);
});
When('the user clicks the submit button', async function () {
  await page.locator('#showInput').click();
});
Then('the message {string} should be displayed on the page', async function (message: string) {
  await expect(page.locator('#message')).toHaveText(message);
});

Code Walkthrough:

• The file imports Given, When, and Then from @cucumber/cucumber, expect from @playwright/test, and the shared page from world.ts. The hooks in world.ts already open and close the browser.
• The Given step opens the form page and waits for network activity to settle. In the re-run, a fill that ran before the page finished loading its scripts was lost and the result stayed empty; waiting for networkidle made the scenario pass on every repeat.
• The first When step fills the message field by its placeholder. On the current playground, the ID #user-message matches three elements, so Playwright's strict locators reject it; a unique locator avoids that.
• The second When step clicks the Get Checked Value button, whose ID is #showInput.
• The Then step uses the auto-waiting toHaveText assertion, which retries until the message appears instead of reading the text once.

Running the Tests

Run the following command to execute the tests:

pnpm exec cucumber-js

The progress formatter prints one dot per passing step, including the two hooks. This is the output from the September 2026 re-run of this exact scenario on Chrome 153:

......

1 scenario (1 passed)
6 steps (6 passed)
0m 19.824s (0m 19.798s executing your code)

Running Scenarios by Tag and Checking Step Mapping

Tag a scenario by adding a line such as @smoke above it in the feature file. Then use these cucumber-js options, all listed in its --help output, to control what runs:

# Run only scenarios tagged @smoke
pnpm exec cucumber-js --tags @smoke

# Check that every step has a definition, without opening a browser
pnpm exec cucumber-js --dry-run

# Run scenarios across 2 worker processes
pnpm exec cucumber-js --parallel 2

# Retry a failing scenario once before marking it failed
pnpm exec cucumber-js --retry 1

Running the Tests in Headed Mode

To watch the browser while tests run, launch it in headed mode in world.ts:

Before(async () => {
  browser = await chromium.launch({
    headless: false, // <-- Change this to false
  });
  page = await browser.newPage();
});

Note: Headed mode helps with debugging, but keep CI runs headless: most CI runners have no display, and headed runs are slower.

How to Generate Reports Using Playwright With Cucumber?

The cucumber-html-reporter package turns Cucumber's JSON output into an HTML report that shows which scenarios passed and failed. Install it along with dayjs, which timestamps the report file name:

pnpm add -D cucumber-html-reporter && pnpm add dayjs

Create a file called report.js in the root of the project:

const reporter = require("cucumber-html-reporter");
const dayjs = require("dayjs");
const fs = require("fs");
const currentDate = dayjs().format("YYYY_MM_DD_HH_mm_ss_SSS");
const options = {
  brandTitle: "Feature Test Report",
  theme: "bootstrap",
  jsonFile: "Reports/cucumber_report.json",
  output: "Reports/cucumber_report_" + currentDate + ".html",
  screenshotsDirectory: "./Screenshots/",
  storeScreenshots: true,
  reportSuiteAsScenarios: true,
  launchReport: true,
};
// Making the directory if it doesn't exist
if (!fs.existsSync("Reports")) {
  fs.mkdirSync("Reports");
}
if (!fs.existsSync("Screenshots")) {
  fs.mkdirSync("Screenshots");
}
reporter.generate(options);

The options control the report:

• brandTitle - The title of the report.
• theme - The visual theme of the report.
• jsonFile - The location of the JSON file that contains the test results.
• output - The location of the generated HTML report.
• screenshotsDirectory - Where screenshots taken on failure are stored.
• storeScreenshots - Whether to store screenshots.
• reportSuiteAsScenarios - Whether to report the suite as scenarios.
• launchReport - Whether to open the report in your browser once it's generated.

Next, add a JSON formatter to the format list in cucumber.js:

module.exports = {
  default: {
    paths: ['tests/features/'],
    requireModule: ['tsx/cjs'],
    require: ['tests/steps/**/*.ts'],
    format: ['progress', 'json:Reports/cucumber_report.json'],
  },
};

After the tests run, Cucumber writes the results to the JSON file named in the json:Reports/cucumber_report.json entry, and report.js converts that file into HTML. Add both steps as a script in package.json:

{
  "scripts": {
    "test": "cucumber-js && node report.js"
  }
}

Run the tests with pnpm test. The report lands in the Reports directory as cucumber_report_<date>.html and opens in your default browser:

.
└── playwright-cucumber
   ├── ...
   ├── Reports/
   │   └── cucumber_report_<date>.html
   └── ...

Taking Screenshots on Failure

A screenshot of the browser at the moment of failure shows what the page looked like when the assertion broke. Update the After hook in world.ts to capture one:

After(async function (scenario) {
  if (scenario.result?.status === 'FAILED') {
    const screenshot = await page.screenshot({
      path: `./Screenshots/${scenario.pickle.name}.png`,
    });
    this.attach(screenshot, 'image/png');
  }
  await browser.close();
});

The hook checks scenario.result.status. On failure, page.screenshot saves an image named after the scenario to the Screenshots directory, and this.attach embeds it in the report.

To simulate a failure, change the expected message in submit-form.ts:

Then('the message {string} should be displayed on the page', async function (message: string) {
  await expect(page.locator('#message')).toHaveText('Hello, World'); // <-- Changed this to "Hello, World"
});

Run pnpm test again. The scenario fails, and a new screenshot appears in the Screenshots directory with the name of the scenario:

└── playwright-cucumber
   ├── ...
   ├── Screenshots/
   │   └── Submit a form with a message.png
   └── ...

Here is the screenshot generated when the test failed: