playwright-cucumber-conventions

Playwright + Cucumber 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('...', async function () {
  await bridge.base.goto(process.env.BASEURL!);
});

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

Locator Strategy (CRITICAL — follow this priority)

1. For form fields: ALWAYS locate by field label

When the recorded hint includes a fieldLabel, use label-based ancestor navigation:

private getDropdownByLabel(labelText: string) {
  const label = this.page.locator(`label:has-text("${labelText}")`).first();
  return label.locator('xpath=ancestor::div[.//button[contains(@data-test,"Dropdown")]][1]')
    .locator('button[data-test*="Dropdown"]');
}

private getInputByLabel(labelText: string) {
  const label = this.page.locator(`label:has-text("${labelText}")`).first();
  return label.locator('xpath=ancestor::div[.//input][1]').locator('input');
}