@qavajs/playwright-runner-adapter

Adapter to run Cucumber BDD tests via the Playwright test runner. Write feature files in Gherkin, execute them with Playwright's parallelism, reporting, and fixture system.

Table of Contents

• Installation
• Quick Start
• Configuration Reference
• World Classes
  • TestWorld
  • PlaywrightWorld
  • Custom World
• Hooks
• Step Arguments
• Template Steps
• Filtering Tests
  • Tag Expressions
  • Predicate Filter
• Parallelism
• JavaScript / CommonJS Support
• Limitations

Installation

npm install @qavajs/playwright-runner-adapter

Quick Start

1. Create a Cucumber config file

// cucumber.config.ts
import { defineConfig } from '@qavajs/playwright-runner-adapter';

export default defineConfig({
    paths: ['test/features/**/*.feature'],
    require: ['test/step_definitions/**/*.ts']
});

2. Point Playwright at it

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
    testMatch: 'cucumber.config.ts'
});

3. Run tests

npx playwright test

Configuration Reference

defineConfig accepts standard Cucumber options:

| Option | Type | Description | |---|---|---| | paths | string[] | Glob patterns for .feature files | | require | string[] | Glob patterns for step definition files (CommonJS require) | | import | string[] | Glob patterns for step definition files (ESM import) | | requireModules | string[] | Modules to require before step definitions (e.g. ts-node/register) |

// cucumber.config.ts
import { defineConfig } from '@qavajs/playwright-runner-adapter';

export default defineConfig({
    paths: ['test/features/**/*.feature'],
    require: ['test/step_definitions/**/*.ts'],
    requireModules: [],
});

World Classes

TestWorld

Base world class with Cucumber lifecycle methods and Playwright's test and expect.

import { TestWorld } from '@qavajs/playwright-runner-adapter';

| Property | Type | Description | |---|---|---| | test | TestType | Playwright test instance (default or custom) | | expect | ExpectType | Playwright expect instance (default or custom) | | attach | function | Attach files/data to the test report | | log | function | Log data to console | | parameters | string | Cucumber world parameters | | config | any | Cucumber config object | | supportCodeLibrary | any | Access to the loaded support code library |

executeStep(text, extraParam?) — programmatically invoke a step by its text:

When('composite step', async function (this: PlaywrightWorld) {
    await this.executeStep('I open the home page');
    await this.executeStep('I click "Login"');
});

PlaywrightWorld

Extends TestWorld with Playwright browser fixtures pre-wired.

import { PlaywrightWorld } from '@qavajs/playwright-runner-adapter';

| Property | Type | Description | |---|---|---| | page | Page | Current Playwright page | | context | BrowserContext | Current browser context | | browser | Browser | Browser instance | | request | APIRequestContext | API request context |

Use PlaywrightWorld (or a class extending it) as your world constructor when you need browser access in step definitions:

import { setWorldConstructor, PlaywrightWorld } from '@qavajs/playwright-runner-adapter';

setWorldConstructor(PlaywrightWorld);

Given('I open {string}', async function (this: PlaywrightWorld, url: string) {
    await this.page.goto(url);
});

Custom World

Extend PlaywrightWorld to add custom fixtures or override test/expect.

Connecting custom Playwright fixtures:

import { test as base, expect as baseExpect, Page } from '@playwright/test';
import { setWorldConstructor, PlaywrightWorld } from '@qavajs/playwright-runner-adapter';

type MyFixtures = {
    settingsPage: SettingsPage;
};

const customTest = base.extend<MyFixtures>({
    settingsPage: async ({ page }, use) => {
        await use(new SettingsPage(page));
    },
});

const customExpect = baseExpect.extend({
    async toBeValid(received) {
        // custom matcher implementation
    },
});

class MyWorld extends PlaywrightWorld {
    settingsPage!: SettingsPage;

    // Override test and expect with extended versions
    test = customTest;
    expect = customExpect;

    // init is called with all fixtures — map them to world properties here
    init = ({ page, settingsPage }: { page: Page; settingsPage: SettingsPage }) => {
        this.page = page;
        this.settingsPage = settingsPage;
    };
}

setWorldConstructor(MyWorld);

The init function receives Playwright fixtures as its argument. Its signature determines which fixtures Playwright injects — list only the fixtures you need.

Hooks

All standard Cucumber hooks are supported. Hooks run as named Playwright steps and appear in the trace viewer and HTML report.

import {
    Before, After,
    BeforeStep, AfterStep,
    BeforeAll, AfterAll,
    ITestCaseHookParameter,
    ITestStepHookParameter,
} from '@qavajs/playwright-runner-adapter';

// Runs before each scenario
Before(async function (this: PlaywrightWorld, { pickle }: ITestCaseHookParameter) {
    console.log('Starting:', pickle.name);
});

// Runs after each scenario — result is available
After(async function (this: PlaywrightWorld, { result }: ITestCaseHookParameter) {
    if (result?.status === 'FAILED') {
        await this.page.screenshot({ path: 'failure.png' });
    }
});

// Runs before/after each step
BeforeStep(async function (this: PlaywrightWorld, { pickleStep }: ITestStepHookParameter) {
    console.log('Step:', pickleStep.text);
});

AfterStep(async function (this: PlaywrightWorld, { result }: ITestStepHookParameter) {
    console.log('Step status:', result?.status);
});

// Runs once per worker process
BeforeAll(async function () {
    // setup shared state
});

AfterAll(async function () {
    // teardown shared state
});

Named hooks — supply a name to make the hook identifiable in reports:

Before({ name: 'Authenticate user' }, async function (this: PlaywrightWorld) {
    // ...
});

Scoped hooks — use a tag expression to run hooks only for matching scenarios:

Before({ tags: '@needsAuth' }, async function (this: PlaywrightWorld) {
    // runs only for scenarios tagged @needsAuth
});

Step Arguments

Data Tables:

When I submit the form
  | field    | value   |
  | username | alice   |
  | password | secret  |

import { When, DataTable } from '@qavajs/playwright-runner-adapter';

When('I submit the form', async function (this: PlaywrightWorld, table: DataTable) {
    const rows = table.hashes(); // [{ field: 'username', value: 'alice' }, ...]
});

Doc Strings:

When I set the body
  """
  {"key": "value"}
  """

When('I set the body', async function (this: PlaywrightWorld, body: string) {
    // body === '{"key": "value"}'
});

Template Steps

Template composes a step out of other existing steps, eliminating the need for custom step implementations for common sequences.

import { When, Template } from '@qavajs/playwright-runner-adapter';

When('I log in as {string}', Template((username: string) => `
    I fill in "username" with "${username}"
    I fill in "password" with "secret"
    I click "Submit"
`));

Each non-empty line in the returned string is executed as an individual step against the current world. Steps run sequentially; a failure stops the sequence.

Filtering Tests

Tag Expressions

Use tags to translate a Cucumber tag expression into a Playwright grep pattern:

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { tags } from '@qavajs/playwright-runner-adapter';

export default defineConfig({
    grep: tags('@smoke and not @slow'),
});

Supports the full Cucumber tag expression syntax: and, or, not, parentheses.

Predicate Filter

Use filter when you need arbitrary logic to select scenarios:

import { defineConfig } from '@playwright/test';
import { filter } from '@qavajs/playwright-runner-adapter';

export default defineConfig({
    grep: filter(name => name.includes('login')),
});

The predicate receives the full test name (feature + scenario title + tags) and should return true to include the test.

Parallelism

Playwright projects let you run subsets of scenarios in parallel or serially:

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
import { tags } from '@qavajs/playwright-runner-adapter';

export default defineConfig({
    testMatch: 'cucumber.config.ts',
    projects: [
        {
            name: 'parallel',
            grep: tags('not @serial'),
            use: devices['Desktop Chrome'],
            fullyParallel: true,
        },
        {
            name: 'serial',
            grep: tags('@serial'),
            use: devices['Desktop Chrome'],
            fullyParallel: false,
        },
    ],
});

Tag scenarios that must run serially with @serial (or any tag of your choice) and keep everything else fully parallel.

To get the current worker index inside a step, use this.test.info().parallelIndex.

JavaScript / CommonJS Support

If your step definitions are plain JavaScript (.js), import from the ./js entrypoint to avoid TypeScript overhead:

// cucumber.config.js
const { defineConfig } = require('@qavajs/playwright-runner-adapter/js');

module.exports = defineConfig({
    paths: ['test/features/**/*.feature'],
    require: ['test/step_definitions/**/*.js'],
});

// step_definitions/steps.js
const { Given, When, Then, PlaywrightWorld } = require('@qavajs/playwright-runner-adapter/js');

Limitations

• ES modules — not supported for Node.js < 22 (where experimental ESM require is available). Use CommonJS or TypeScript with ts-node.
• setParallelCanAssign — not supported. Use Playwright projects with fullyParallel to control parallelism.
• CUCUMBER_PARALLEL / CUCUMBER_TOTAL_WORKERS / CUCUMBER_WORKER_ID — not supported. Use this.test.info().parallelIndex and this.test.info().workerIndex instead.