---
description: Generate exhaustive Gherkin BDD scenarios for a single page using the bdd-gherkin skill
argument-hint: "<URL> [output-dir] [auth-env-file] [tester-roles]"
---

Selected tester roles (may be empty): ${4:-}

Use the `bdd-gherkin` skill and `playwright-cli` commands to inspect the page at $1 and generate exhaustive Gherkin BDD scenarios for **that page only**. Fall back to the Playwright MCP bridge (`browser_*` tools) only if `playwright-cli` is unavailable or fails.

## Preferred tooling

- **Primary:** `playwright-cli` (`open`, `snapshot`, `goto`, `click`, `fill`, etc.)
- **Fallback:** Playwright MCP (`browser_navigate`, `browser_snapshot`, etc.)

## Workflow

1. **Load the BDD skill**.
   - Read `skills/bdd-gherkin/SKILL.md` first and follow its rules.

2. **Inspect the target page with `playwright-cli` first**.
   - Check whether `playwright-cli` is on PATH. If not, use `npx -p @playwright/cli playwright-cli ...`.
   - Run `playwright-cli open $1` to load the page.
   - Run `playwright-cli snapshot` to capture the accessibility tree, visible fields, buttons, links, tables, and any validation/error messages.
   - If `playwright-cli` cannot be resolved or its commands fail, fall back to the Playwright MCP bridge: use `browser_navigate` to load $1 and `browser_snapshot` to inspect it.
   - If the page requires authentication and an auth env file was provided (`$3`), follow the secure login flow from the `playwright-cli` skill to log in before snapshotting.
   - Identify the primary actor(s), the business capability the page supports, and every interactive element or workflow step on the page.
   - Do **not** navigate away from the page; generate scenarios for the page pointed to by $1 only.

3. **Derive business context**.
   - From the page content, determine:
     - The business feature/capability (e.g., "Transfer Money", "User Login", "Apply for Loan").
     - The primary actor(s) (e.g., customer, admin, visitor).
     - The business value provided by the page.
     - Required fields, optional fields, constraints, and possible outcomes.
   - If the page is ambiguous or critical business rules are not visible (e.g., user roles, backend rules), ask **one or two concise clarifying questions** before generating scenarios. Otherwise, proceed directly.

4. **Generate exhaustive Gherkin scenarios**.
   Cover the following categories for the page:

   - **Happy path** — successful completion of the primary action.
   - **Validation / invalid input** — missing required fields, malformed input, out-of-range values, wrong formats.
   - **Edge cases** — boundary values, empty input, maximum/minimum lengths, special characters, whitespace, zero/null amounts.
   - **Business rules / state-based cases** — preconditions that affect behavior (e.g., insufficient balance, locked account, existing record).
   - **Error / negative cases** — visible error messages, disabled actions, failed submissions.
   - **UI / interaction cases** — toggles, show/hide password, dropdown dependencies, disabled fields, cancel/reset actions.
   - **Accessibility / usability cases** — keyboard focus, visible labels, error announcement (if inferable from the page).

   Additionally, if the "Selected tester roles" value at the top of this prompt is **not empty**, adopt the perspective of each listed tester role (e.g. accessibility tester, security tester, performance tester, functional tester) and generate additional scenarios that role would write for this page. Examples: an accessibility tester produces scenarios for screen-reader labels, focus order, and color-contrast issues; a security tester produces scenarios for injection attempts, unauthorized access, and data exposure; a performance tester produces scenarios for large payloads and slow-network handling. Keep these role-specific scenarios business-readable and in the same Gherkin style as the rest — tag them with a role tag such as `@accessibility`, `@security`, or `@performance`. If no tester roles are listed, skip this and produce only the default coverage above.

5. **Follow Gherkin best practices**.
   - Use a single-focused Scenario for each behavior.
   - Use **exactly one `When` action per scenario**; move setup details into `Given` or `Background`.
   - Use `Background` liberally for shared preconditions.
   - Use data tables when a `Given` step has two or more fields.
   - Use business language, not Selenium/implementation detail.
   - Include a business value statement (`As a ... I want ... So that ...`) when it adds clarity.
   - Use Scenario Outlines only when data variation is the central focus.
   - Keep tags minimal.

6. **Save the feature file**.
   - Write the generated Gherkin to `${2:-tests/features/}/<page-name>.feature`.
   - Use a clear, kebab-case file name derived from the page (e.g., `transfer-money-page.feature`, `login-page.feature`).
   - If the page supports multiple distinct capabilities, split into multiple feature files in the output directory.

## Authentication

If the site requires login, handle credentials securely:

1. **Preferred: provide an auth env file** as the third argument (`$3`).
   - The env file should contain variables such as:
     ```bash
     BDD_AUTH_URL=https://example.com/login
     BDD_USERNAME=user@example.com
     BDD_PASSWORD=secret
     ```
   - Load the file in a single bash command, use the values immediately to log in via `playwright-cli` (e.g., `open` the login page, then `fill` the credentials), and **do not echo, log, or persist the values anywhere**.
   - Do not include the env file or its values in generated `.feature` files, snapshots, or test code.
   - Mark the env file in `.gitignore` and delete it when the session is complete.

2. **Fallback: manual login**.
   - If no env file is provided, open the login page with `playwright-cli open` and ask the user to complete login manually in the browser session.
   - Then continue generating scenarios from the authenticated state.

3. **Never** ask the user to paste credentials into the chat, and **never** hardcode credentials into generated files.

## Output

- The saved `.feature` file path(s).
- A brief summary of the scenario categories covered (happy path, validation, edge cases, errors, etc.).
- Any clarifying assumptions made about business rules or user roles.
- How authentication was handled (env file or manual).