003-playwright-cucumber-conventions

Playwright + Cucumber BDD Framework Conventions

Architecture Pattern

This project uses the Bridge pattern for Playwright + Cucumber BDD testing:

Steps → Bridge → Page Objects + Helpers
                  ├── PlaywrightWrapper (click, fill, goto, wait)
                  ├── Assert (assertions)
                  ├── YamlHelper / JsonHelper (test data)
                  └── CommonHelper (utilities, random data)

Adding New Tests

1. Feature file: Create src/test/features/<name>.feature using Gherkin syntax
2. Step definitions: Create src/test/steps/<name>Step.ts, use Bridge to access page objects
3. Page object: Create src/test/pages/<Name>Page.ts as singleton with PlaywrightWrapper
4. Register page: Add the new page to src/hooks/bridge.ts

Step Definition Pattern

import { Given, When, Then, BeforeStep } from '@cucumber/cucumber';
import Bridge from '../../hooks/bridge';
import { fixture } from '../../hooks/pageFixture';

let bridge: Bridge;
BeforeStep(() => { bridge = new Bridge(fixture.page); });

Given('the user is on the home page', async function () {
  await bridge.base.goto(process.env.BASEURL!);
});

When('the user clicks {string}', async function (buttonText: string) {
  await bridge.homePage.clickButton(buttonText);
});

Then('the user sees {string}', async function (expectedText: string) {
  await bridge.assert.toContainText(expectedText);
});

Page Object Pattern

• Singleton with getInstance(page)
• Store private page: Page reference for direct Playwright API access when wrappers are insufficient
• Use PlaywrightWrapper for simple interactions, direct page for complex ones
• Store locators as class properties

import { Page } from '@playwright/test';
import PlaywrightWrapper from '../../helper/wrapper/PlaywrightWrappers';
import Assert from '../../helper/wrapper/assert';

export default class ExamplePage {
  private static instance: ExamplePage;
  private page: Page;
  base: PlaywrightWrapper;
  assert: Assert;

  private constructor(page: Page) {
    this.page = page;
    this.base = PlaywrightWrapper.getInstance(page);
    this.assert = Assert.getInstance(page);
  }

  public static getInstance(page: Page): ExamplePage {
    if (!ExamplePage.instance) {
      ExamplePage.instance = new ExamplePage(page);
    }
    return ExamplePage.instance;
  }

  async clickButton(text: string) {
    await this.page.getByRole('button', { name: text }).click();
  }
}