script-to-bdd-converter

Script-to-BDD Converter

When the user asks to convert a recorded script to Playwright + Cucumber tests, follow this protocol. The goal is to generate tests that pass on the first run by using the rich metadata captured during recording.

Conversion Workflow

Step 1: Read the Recorded Script

Read the scripts/<name>.md file. It contains:

• Steps with (hint: ...) blocks that have locator metadata
• A ## Form Fields Summary section with all form controls and their attributes
• Auth credentials, base URL, and pre-requisites

Step 2: Identify Pages (Page Object Decomposition)

Group steps by the URL they operate on. Each distinct page/URL becomes a Page Object:

URL Pattern	Page Object
/login	LoginPage
/dashboard	DashboardPage
/settings	SettingsPage
/users	UsersPage
/users/create	CreateUserPage
/users/:id	UserDetailsPage

Step 3: Generate Page Objects

For each page, create src/test/pages/<PageName>.ts:

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;
  }
  // ... methods
}

Step 4: Build Locators from Recorded Hints

This is the most critical step. For each element interaction in the recorded script, choose the locator strategy using the hint metadata:

Decision tree for locator selection:

1. Does the hint have locators.name? → Use `input[name="..."]`
2. Does the hint have locators.id? → Use `#id`
3. Is the element a form dropdown with fieldLabel?
   → Use label-based ancestor navigation (see pattern below)
4. Does the hint have locators.dataTest and ambiguity.sameDataTest === 1?
   → Use `[data-test="..."]`
5. Is the text unique (ambiguity.sameText === 1)?
   → Use `text=...` or `button:has-text("...")`
6. Text is NOT unique (ambiguity.sameText > 1)?
   → MUST use fieldLabel + ancestor navigation to disambiguate