Cypress

---
description: Generate Cypress E2E tests — BRD Mode (full coverage from a BRD file) or Scenario Mode (single test from a description). Gated workflow with QA approval at every step. Production URL guard prevents execution against prod.
argument-hint: "Path to a BRD file (BRD Mode): docs/business/{module}/{slug}.md — OR — plain description (Scenario Mode): 'add customer with duplicate check'"
---

# Cypress E2E Test Generator (`/cypress`)

You are a Cypress test engineer. This command generates ready-to-run Cypress E2E tests following all project conventions in `cypress_framework/`.

**Read the skill before starting**: `.claude/skills/cypress-tests/SKILL.md` — it contains all templates, field interaction patterns, naming conventions, browser MCP steps, and the full checklist. The skill is the source of truth for test structure; this command is the orchestration entry point.

---

## Mode Detection

Inspect `$ARGUMENTS`:

1. If `$ARGUMENTS` ends with `.md` OR matches a file path that exists → **BRD Mode** (full suite generation).
2. Otherwise → **Scenario Mode** (single test generation).

Announce which mode is active before proceeding.

---

## Production Guard (BOTH modes — check before any phase)

After the environment URL is known (either from `$ARGUMENTS` context or from AskQuestion), check it:

1. URL contains `prod` (case-insensitive) → **BLOCKED**
2. URL matches `url_prod` or `url_prod_new` values from `cypress_framework/cypress/fixtures/fixtures/all_fixtures.json` → **BLOCKED**
3. URL does NOT contain `dev`, `staging`, `test`, `local`, `localhost` → **BLOCKED**

If blocked, print and stop:

BLOCKED: Production URL detected (). /cypress does not run against production environments. Provide a dev or staging URL to continue.

Block BOTH browser MCP navigation AND Cypress CLI execution.

---

# BRD Mode

**Input**: path to a BRD file (e.g. `docs/business/orders/order-export.md`)
**Output**: a suite of Cypress test files + fixture updates, one test per approved scenario

## Core Principles

- **Read the skill first**: `.claude/skills/cypress-tests/SKILL.md` before generating any test.
- **Use TodoWrite**: create the todo list at Phase B1 start with all 4 phases; mark each in_progress → completed as you go.
- **Never skip gates**: Phases B2 and B3c/B3e are mandatory stops. Do not proceed without explicit QA approval.
- **One test at a time**: complete the full loop (B3a–B3e) for test k before starting k+1.

---

## Phase B1: Read BRD & Extract Test Plan

**TodoWrite** at start: `[B1 in_progress, B2–B4 pending]` + placeholders for each test loop.

1. Read the BRD file at the given path.
2. If the BRD has cross-links to a design doc or spec (`docs/design/`, `docs/bundles/`), read those too for additional flow context.
3. Ask for the target environment URL (used for browser MCP selector discovery and Cypress CLI run).
4. **Production Guard** — check the URL now.
5. Extract test scenarios from these BRD sections:

   | BRD Section | Extraction rule |
   |-------------|-----------------|
   | **Functional Requirements** (FR-N) | Each FR = one or more happy-path tests |
   | **Edge Cases & Error Scenarios** | Each row = one negative/edge test |
   | **Acceptance Criteria** (AC-N) | Each AC = one verification test |
   | **High-Level Flow** | Happy path end-to-end |
   | **User Roles / Permissions** | Each role difference = one permission test |

6. Produce a numbered test plan:

Test Plan —

1. [create] FR-1: Create new with valid data → verify saved
2. [edge] FR-1 + EC-1: Create with duplicate name → verify deduplication modal
3. [filter] FR-2: Filter by status → verify list result
4. [negative] EC-2: Submit form with empty required fields → verify validation errors
5. [permission] AC-3: Non-admin cannot access → verify redirect/403 ...

Each entry: `[template type]`, source reference, scenario description.

---

## Phase B2: Gate — QA Approves Test Plan (mandatory stop)

Present the full test plan. Ask:

> **Review the test plan above.**
>
> - `approve` — proceed with all listed tests
> - `add: <new scenario>` — add extra scenarios; AI appends and re-presents
> - `remove: <N>` — remove test N from the list
> - `edit: <N> <new description>` — change a scenario description
>
> Reply with one or more of the above. Only after final `approve` will generation begin.

Do NOT proceed to Phase B3 until explicit `approve`.

Update TodoWrite: B2 completed, add individual todos for each approved test (B3-k).

---

## Phase B3: Loop — Generate & Approve Each Test (k = 1..N)

Repeat for every approved test scenario k. Mark `B3-k` in_progress at start of each iteration.

### B3a — Discover selectors (browser MCP)

Follow the selector discovery steps from `.claude/skills/cypress-tests/SKILL.md` § Browser MCP.

- `browser_navigate` → target page on the env URL
- `browser_lock` → lock tab
- `browser_snapshot` → ARIA tree + refs
- Extract real CSS selectors, `data-*` attributes, form field names, button text
- For Select2/autocomplete: click to open, snapshot dropdown
- For multi-step forms: capture each step
- `browser_lock(unlock)` when done

Auth note: if login is required, ask QA to log in manually in the browser tab, or provide a session cookie value.

### B3b — Generate test file + fixture data

- Pick the correct template from `.claude/skills/cypress-tests/SKILL.md` § Templates
- Assign the next available `NNN` number (read existing files in `cypress_framework/cypress/e2e/`)
- Generate `cypress/e2e/NNN_scenarioName.cy.js` with real selectors, guard pattern, session boilerplate, result tracking
- Update the appropriate fixture JSON with new selectors/data
- If reusable logic > 15 lines, extract to `cypress/support/commands.js`

### B3c — Gate — QA Approves Test k (mandatory stop)

Present:
- Full generated test file content
- Fixture JSON additions/changes
- Any new custom command (if added)

Ask