If you've worked with Playwright for a while, you've probably had this conversation with a stakeholder or a QA lead:

"Can we write our tests in Gherkin? The business wants to be able to read the test cases."

The usual answer is to reach for CucumberJS or playwright-bdd. Both work, but they come with a cost, you now maintain .feature files alongside your test code, wire up a step definition runner, and manage a parallel toolchain that sits on top of Playwright. Your Playwright runner is effectively replaced.

I wanted the readability of BDD without any of that overhead. So I built playwright-gherkin-steps.

What It Is

A lightweight pattern, three helper files that adds Gherkin-style Given, When, Then, and And steps directly to native Playwright test() blocks. No .feature files. No separate runner. No extra runtime dependencies beyond Playwright itself.

Your tests look like this:

test("new user can register successfully", async ({ page }) => {
  const signupPage = new SignupPage(page);
  registerSteps(signupPage);
  const { Given, When, Then } = createGherkin();

  await Given("User navigates to AutomationExercise");

  await When(
    "User submits the signup form",
    `
    | name     | email                    |
    | John Doe | testuser@mailinator.com  |
  `,
  );

  await Then("User should be on the account info page");
});

And your page object looks like this:

export class SignupPage {
  constructor(private page: Page) {}

  @step("Given User navigates to AutomationExercise")
  async navigate() {
    await this.page.goto("https://automationexercise.com/login");
  }

  @step("When User submits the signup form")
  async submitSignupForm(table: DataTable) {
    const { name, email } = table.first();
    await this.page.fill("[data-qa='signup-name']", name);
    await this.page.fill("[data-qa='signup-email']", email);
    await this.page.click("[data-qa='signup-button']");
  }

  @step("Then User should be on the account info page")
  async assertOnAccountInfoPage() {
    await expect(this.page).toHaveURL(/.*signup/);
  }
}

That's it. Native Playwright test() blocks, page object pattern you already know, and BDD-style readability on top.

The Problem With Existing BDD Solutions

The most common BDD solutions for Playwright are CucumberJS and playwright-bdd. Both require you to maintain separate .feature files with your Gherkin scenarios and write matching step definitions in a separate file, keeping the two in sync as your tests evolve. In most projects I've seen, those .feature files end up being written by developers anyway, so you're paying the framework cost without the intended benefit of business-readable scenarios owned by non-developers.

playwright-bdd keeps the Playwright runner, which is good. But it introduces its own overhead of having to convert your .feature files into spec.ts files as a build step before Playwright can run them. More moving parts, more to maintain.

CucumberJS replaces the Playwright runner entirely with its own — and the Playwright runner is one of the most powerful things about Playwright. Think about what you give up:

• Playwright's HTML report - rich, interactive, with traces, screenshots, and video attached to every failure
• Trace Viewer — the ability to replay every action, network request, and DOM snapshot from a failed test run
• test.step() — native step grouping that shows up in the report with timings per step
• Fixtures — Playwright's dependency injection system for sharing state cleanly across tests
• UI Mode — the interactive watch mode for debugging tests live in a browser

When you replace the Playwright runner with CucumberJS's runner, all of that goes away or has to be laboriously re-wired. You're essentially using Playwright as a browser automation library and throwing away the test framework built around it.

This project takes the opposite approach: keep the Playwright runner, add the readability.

How It Works

The implementation is three files.

1. @step Decorator —helpers/StepRegistry.ts

The @step decorator registers a page object method under a description string at class definition time:

export function step(description: string) {
  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor,
  ) {
    stepRegistry.set(description.toLowerCase(), {
      instance: null,
      method: descriptor.value,
    });
    return descriptor;
  };
}

registerSteps(instance) then binds the live page object instance to each registered method, so this.page works correctly when the step runs.

runStep(description) looks up and executes the step — and wraps it in Playwright's native test.step() so it appears in the HTML report.

2. DataTable - helpers/DataTable.ts

Honestly, while working with native Playwright, the one thing I do miss from Cucumber is the DataTable. A clean, highly readable data structure that clearly depicts the actual data being passed into a test step. I've always had a soft spot for the pipe-delimited table format offered by Cucumber.

That need was actually a big part of why I built this. And importantly, you don't need to use Given/When/Then at all to benefit from it. The DataTable class is completely standalone, if you just want clean, structured test data in your native Playwright tests without adopting any BDD vocabulary, you can use it on its own.

The DataTable class parses a pipe-delimited string into an array of row objects keyed by the header row:

const table = new DataTable(`
  | name     | email                |
  | John Doe | john@mailinator.com  |
  | Jane Doe | jane@mailinator.com  |
`);

table.first(); // { name: 'John Doe', email: 'john@mailinator.com' }
table.hashes(); // array of all rows
table.column("name"); // ['John Doe', 'Jane Doe']

Empty cells are preserved as empty strings, they don't shift subsequent columns.

3. Gherkin Context - helpers/Gherkin.ts

createGherkin() returns Given, When, Then, and And as async functions. Each accepts an optional second argument — either an inline template literal string or a pre-built DataTable instance — and resolves it transparently before calling runStep:

// Option 1 — inline template literal
await When(
  "User submits the signup form",
  `
  | name     | email              |
  | John Doe | john@example.com   |
`,
);

// Option 2 - pre-defined DataTable variable
const table = new DataTable(`
  | name     | email              |
  | John Doe | john@example.com   |
`);
await When("User submits the signup form", table);

Your page object method always receives a DataTable instance regardless of which style you used.

Playwright HTML Report Integration

Because every Given/When/Then call goes through runStep, which wraps execution in test.step(), your HTML report automatically breaks down each test by step:

✓ new user can register successfully

    ✓ Given User navigates to AutomationExercise          45ms
    ✓ When User submits the signup form                   312ms
    ✓ Then User should be on the account info page         28ms
    ✓ When User fills account personal information        189ms
    ✓ When User fills address information                 276ms
    ✓ When User clicks Create Account                     534ms
    ✓ Then Account created page should be shown            61ms
    ✓ When User continues after account creation          198ms
    ✓ Then User should be logged in as                     44ms

No extra configuration. The step labels in the report exactly match what you wrote in the test.

Two Styles: Pick What Fits

The project supports two styles depending on how much BDD vocabulary you want.

Style 1 - Full BDD with Given/When/Then:

Tests read like Gherkin scenarios. Best for teams that want maximum readability or stakeholder visibility.

await Given("User navigates to AutomationExercise");
await When(
  "User submits the signup form",
  `
  | name     | email                   |
  | John Doe | testuser@mailinator.com |
`,
);
await Then("User should be on the account info page");

Style 2 - DataTable only, no BDD layer:

Call page object methods directly, but pass structured DataTable objects instead of raw strings. Best for teams that want clean data management without adopting the full BDD vocabulary.

const signupData = new DataTable(`
  | name     | email                   |
  | John Doe | testuser@mailinator.com |
`);

await signupPage.submitSignupForm(signupData);

Both styles live in the same project. You can mix and match per test file.

Getting Started

The project is on GitHub with full setup instructions, both usage styles documented with working examples against automationexercise.com, and a tsconfig.json that works out of the box.

👉 github.com/anubhav-chattopadhyay/playwright-gherkin-steps

Copy the three files in helpers/ into your project and you're done. No additional dependencies, no configuration beyond enabling experimentalDecorators in your tsconfig.json.

What's Next

A few things I'm considering adding:

• Step hooks - Before and After equivalents that run around each step
• Step catalog - a utility that lists all registered steps across page objects, useful for larger projects
• Variable substitution in step names — so you can write @step("When User logs in as {role}") and match it dynamically

If any of those sound useful to you, open an issue or drop a comment below. And if you end up using this in your project, I'd love to hear how it fits.