Cucumber-JS with Playwright
On this page
Gherkin does not care what language runs it. This chapter writes a second feature, for the Playwright team's TodoMVC demo, and runs it with Cucumber-JS, the official JavaScript implementation, driving the browser with Playwright. The concepts from chapters 3 to 6 carry over one to one; what changes is how state is shared (a World object instead of dependency injection) and how the browser is started.
A note on the combination: Playwright has its own test runner, @playwright/test, with fixtures, retries, tracing and parallelism built in. Cucumber-JS replaces that runner, so you use the Playwright library and build those parts yourself. Choose Cucumber-JS when the Gherkin layer is the point (the business reads and reviews the scenarios). If it is not, the Playwright course with @playwright/test is the simpler choice.
Set up the project#
mkdir cucumber-js-playwright && cd cucumber-js-playwright
npm init -y
npm pkg set type=module
npm install --save-dev @cucumber/cucumber@13.3.0 playwright@1.65.0
npx playwright install chromium
type=module lets every file use import. The course pins the versions it was run with; Cucumber-JS 13 supports Node.js 22, 24 and 26 or newer (the course ran on Node.js 22).
cucumber.js configuration
features/todo.feature the Gherkin
features/support/world.js World, hooks, browser setup
features/step_definitions/todo.steps.js
Configuration#
cucumber.js in the project root holds the default profile:
export default {
paths: ['features/**/*.feature'],
import: ['features/support/**/*.js', 'features/step_definitions/**/*.js'],
format: ['progress', 'html:reports/cucumber.html', 'junit:reports/cucumber.xml'],
};
import is the ESM equivalent of the glue path; use require instead if your project is CommonJS. format works like the plugins in the Java runner: progress prints a dot per step, and the HTML and JUnit reports land in reports/.
The feature#
Feature: Keeping a todo list
People add the things they need to do and tick them off when they are done.
Scenario: The counter shows what is left to do
Given my todo list is empty
When I add "Buy milk" and "Call the bank"
Then I have 2 items left
Scenario: Completing a todo
Given my todo list contains "Buy milk" and "Call the bank"
When I complete "Buy milk"
Then I have 1 item left
And "Buy milk" is shown as done
Declarative, one When each. This feature uses the first person, which is fine for a single-user app.
The World: per-scenario state#
Cucumber-JS creates a new World object for every scenario, and binds this in every step definition and hook to it. That is its version of chapter 5's PicoContainer: state shared by all steps of one scenario, and nothing shared between scenarios. You customise it by extending World and registering the class with setWorldConstructor.
features/support/world.js:
import { setWorldConstructor, setDefaultTimeout, Before, After, World, Status } from '@cucumber/cucumber';
import { chromium, firefox, webkit } from 'playwright';
setDefaultTimeout(60 * 1000);
const engines = { chrome: chromium, edge: chromium, firefox, safari: webkit };
function testingbotEndpoint(name) {
const capabilities = {
browserName: process.env.TB_BROWSER ?? 'chrome',
browserVersion: 'latest',
platform: process.env.TB_PLATFORM ?? 'WIN11',
'tb:options': {
key: process.env.TB_KEY,
secret: process.env.TB_SECRET,
name,
build: process.env.TB_BUILD ?? 'local',
},
};
return `wss://cloud.testingbot.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`;
}
function executor(action, args) {
return `testingbot_executor: ${JSON.stringify({ action, arguments: args })}`;
}
class TodoWorld extends World {
get onTestingBot() {
return process.env.GRID === 'testingbot';
}
async openBrowser(scenarioName) {
if (this.onTestingBot) {
const engine = engines[process.env.TB_BROWSER ?? 'chrome'];
this.browser = await engine.connect(testingbotEndpoint(scenarioName));
} else {
this.browser = await chromium.launch();
}
this.page = await this.browser.newPage();
}
}
setWorldConstructor(TodoWorld);
Before(async function ({ pickle }) {
await this.openBrowser(pickle.name);
});
After(async function ({ result }) {
if (!this.browser) return;
try {
if (this.onTestingBot) {
const passed = result?.status === Status.PASSED;
await this.page.evaluate(() => {}, executor('setSessionStatus', {
passed,
reason: result?.message?.slice(0, 200) ?? '',
}));
}
} finally {
await this.browser.close();
}
});
-
setDefaultTimeout: Cucumber-JS fails any step or hook that takes longer than 5 seconds by default. Starting a remote browser can take longer, so the limit is raised to 60 seconds. -
Hooks use
function, not arrow functions. An arrow function does not get its ownthis, sothis.pagewould be undefined. The same applies to step definitions. -
pickle.nameis the scenario name; it names the TestingBot session. -
Locally,
chromium.launch()starts a headless Chromium. On TestingBot,connect()attaches to a browser in the cloud through the Playwright endpoint.chromeandedgeuse thechromiumengine,safariuseswebkit. -
Reporting: the
Afterhook receives the scenario's result and sends it with atestingbot_executorcall, the samesetSessionStatusaction documented for Playwright on TestingBot. Thefinallyalways closes the browser.
A step is written as When('I complete {string}', async (title) => { await this.page.click(...) }). It fails with "Cannot read properties of undefined". Why?
Cucumber-JS binds the World to this for regular functions only. An arrow function captures the this of the module, which is undefined in ESM.
Step definitions#
features/step_definitions/todo.steps.js:
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from 'playwright/test';
const APP = 'https://demo.playwright.dev/todomvc/';
async function addTodos(page, ...titles) {
const input = page.getByPlaceholder('What needs to be done?');
for (const title of titles) {
await input.fill(title);
await input.press('Enter');
}
}
Given('my todo list is empty', async function () {
await this.page.goto(APP);
await expect(this.page.getByTestId('todo-item')).toHaveCount(0);
});
Given('my todo list contains {string} and {string}', async function (first, second) {
await this.page.goto(APP);
await addTodos(this.page, first, second);
});
When('I add {string} and {string}', async function (first, second) {
await addTodos(this.page, first, second);
});
When('I complete {string}', async function (title) {
await this.page.getByTestId('todo-item').filter({ hasText: title })
.getByRole('checkbox').check();
});
Then('I have {int} item(s) left', async function (count) {
await expect(this.page.getByTestId('todo-count')).toHaveText(`${count} ${count === 1 ? 'item' : 'items'} left`);
});
Then('{string} is shown as done', async function (title) {
await expect(this.page.getByTestId('todo-item').filter({ hasText: title })).toHaveClass(/completed/);
});
The Cucumber expressions are the same as in Java: {string}, {int}, and the optional item(s). Two Playwright details make these steps robust:
-
Web-first assertions.
expectfromplaywright/test(part of theplaywrightpackage) retries until the condition holds or times out, so there are no sleeps and no "read the counter too early" races. Plainasserton a value you read once would not retry. - User-facing locators: placeholder text, test IDs and roles rather than CSS paths. The Playwright course explains locator choice in detail.
Run it#
Locally:
npx cucumber-js
...........
2 scenarios (2 passed)
11 steps (11 passed)
The step count includes the Before and After hooks, which Cucumber-JS reports as steps. To run on TestingBot, set the environment variables the World reads:
export TB_KEY=your-key
export TB_SECRET=your-secret
GRID=testingbot TB_BROWSER=chrome TB_PLATFORM=WIN11 TB_BUILD=cucumber-js-course npx cucumber-js
When this chapter was run on the grid, the two scenarios became the sessions 4e7fe56c353b-9942dd735c5e-c5976de82ba5-179456362441-07965983 ("The counter shows what is left to do") and bccfa6bdc0fd-2af03346a810-523f2bb8437e-179456364048-49831641 ("Completing a todo"), both reported as passed (Chrome 156 on Windows 11).
Starting the remote browser in the Before hook fails with "function timed out, ensure the promise resolves within 5000 milliseconds". What is the fix?
Cucumber-JS gives every step and hook 5 seconds by default. A cloud browser can take longer to start, so the timeout needs raising; waiting longer inside the hook only makes it time out sooner.
Selenium instead of Playwright#
If your team already has Selenium page objects in JavaScript, Cucumber-JS works the same way with selenium-webdriver: build the driver in the Before hook with new Builder().usingServer('https://hub.testingbot.com/wd/hub'), keep it on the World, report with driver.executeScript('tb:test-result=passed') and quit in After. The Node.js Selenium docs show the capabilities.