---
description: Generate a Playwright test spec from a Gherkin feature file, reusing existing POMs
argument-hint: "<URL> <feature-file> <pom-dir> [output-dir]"
---

Generate a TypeScript Playwright test spec file that implements the Gherkin scenarios from `$2` for the page at `$1`, reusing existing Page Object Models from `$3`. Create new POMs only when absolutely necessary.

## Inputs

- `$1` — URL of the page under test (used to inspect current UI state and validate selectors).
- `$2` — Path to the `.feature` file to implement.
- `$3` — Directory containing existing POM `.ts` files.
- `$4` — Optional output directory for the generated spec. Defaults to `tests/specs/`.

## Workflow

1. **Load the Playwright skill**.
   - Read `skills/playwright-core/SKILL.md` to follow Playwright best practices.

2. **Inspect the page at `$1`**.
   - Prefer `playwright-cli` (`open`, `snapshot`). If unavailable, fall back to Playwright MCP (`browser_navigate`, `browser_snapshot`).
   - Capture the accessibility tree, form fields, buttons, links, tables, and any visible validation or error messages.
   - Do not navigate away from the page unless required to verify a shared component.

3. **Read the feature file**.
   - Read `$2` with the `read` tool.
   - Parse every `Scenario`, `Scenario Outline`, and `Examples` table.
   - Note the `Feature`, `Background`, actors, and expected outcomes.

4. **Discover available POMs**.
   - List all `.ts` files in `$3` using `bash` (e.g., `find $3 -name "*.ts"`).
   - Read every POM file to understand:
     - Which page/component it represents.
     - The public locators and high-level business methods (e.g., `loginAs`, `initiateTransfer`).
     - Whether an exported `test` fixture file exists (e.g., `fixtures.ts`, `index.ts`).
   - Build a mental map of reusable components and cross-page navigation helpers (e.g., `BankLayout`).

5. **Map scenarios to POM methods**.
   - For each Gherkin scenario, decide which existing POM(s) implement the necessary actions and assertions.
   - Reuse existing business methods whenever possible; do not duplicate selector logic in the spec.
   - If a scenario needs a component that is not yet modeled, first check whether it belongs in an existing POM (e.g., a shared layout component, a dialog in a page POM). Only create a new POM file if the gap is significant and reusable.

6. **Generate the Playwright spec**.
   - Write a `.spec.ts` file under `${4:-tests/specs/}` using kebab-case naming derived from the feature (e.g., `login-page.spec.ts`).
   - Use existing fixtures if `$3` exports a `test` object (e.g., `import { test, expect } from '../pom'`). Otherwise, import POM classes and instantiate them in a `test.beforeEach` or per-test helper.
   - Each Gherkin scenario should map to one Playwright `test(...)`.
   - Use `test.describe` to group tests by feature or capability when helpful.
   - Use `test.beforeEach` for shared `Background` preconditions.
   - Use `expect` assertions that match the `Then` steps.
   - For `Scenario Outline` `Examples`, generate one test per example row or use a parameterized loop with `test.each`/`test.describe.each`.
   - Keep tests readable and free of low-level selectors; all selectors should come from POMs.

7. **Cross-check against the live page**.
   - Where practical, verify that the POM methods used in the generated spec actually match the live page elements observed in step 2.
   - If a POM method name suggests behavior that differs from the current page, prefer updating the POM method call or asking the user rather than hardcoding selectors in the spec.

## Output

- Save the generated spec file to `${4:-tests/specs/}<feature-name>.spec.ts`.
- Report:
  - The spec file path.
  - Which POM files were reused and how.
  - Any POMs that were updated or newly created (should be rare).
  - Any scenarios that could not be mapped to existing POMs and why.