/e2e

description: Generate, run, and report Playwright E2E tests traced to spec.md acceptance criteria. Supports accessibility auditing via --a11y. Use when saying "e2e tests", "playwright tests", "run e2e", "generate e2e", "accessibility audit", "a11y test".
version: 1.0.0
argument-hint: "--generate|--run|--a11y <increment-id>"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
context: fork
model: sonnet

E2E Testing — Playwright + AC Traceability

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/e2e.md` exists, read and apply its learnings.

Generate Playwright E2E tests from spec.md acceptance criteria, run them, and produce a structured report that maps pass/fail results to AC-IDs. Consumed by sw:done Gate 2a for automated closure gating.

Modes

| Flag | Action | |------|--------| | `--generate <id>` | Read spec.md → create one `.spec.ts` per US with one `test()` per AC | | `--run <id>` | Execute `npx playwright test` → parse results → write `e2e-report.json` | | `--a11y <id>` | Like `--run` but also scans each page with `@axe-core/playwright` |

Combine `--run` + `--a11y` to get both functional and accessibility results. `--generate` ignores `--a11y` (warn if combined).

---

Step 1: Parse Arguments

Extract mode and increment ID from `$ARGUMENTS`:

# Parse: --generate 0042 | --run 0042 | --a11y 0042 | --run --a11y 0042
MODE="run"       # default
A11Y=false
INCREMENT_ID=""

for arg in $ARGUMENTS; do
  case "$arg" in
    --generate) MODE="generate" ;;
    --run)      MODE="run" ;;
    --a11y)     A11Y=true ;;
    *)          INCREMENT_ID="$arg" ;;
  esac
done

If no increment ID provided, check for an active increment:

ACTIVE=$(find .specweave/increments -maxdepth 2 -name "metadata.json" -exec grep -l '"active"' {} \; 2>/dev/null | head -1)

If still no ID → **STOP**: "No increment ID provided and no active increment found."

Resolve increment path: `.specweave/increments/<id>/`

Step 2: Environment Validation — Playwright Detection

**MANDATORY before any operation.** Detect Playwright installation:

# 1. Find playwright.config
PW_CONFIG=$(find . repositories -maxdepth 4 -name "playwright.config.ts" -o -name "playwright.config.js" 2>/dev/null | head -1)

# 2. Check for @playwright/test in package.json
PW_PACKAGE=$(grep -r '"@playwright/test"' package.json packages/*/package.json repositories/*/*/package.json 2>/dev/null | head -1)

**Decision matrix**:

| Config | Package | Action | |--------|---------|--------| | Found | Found | **Proceed** — use config path | | Missing | Found | **FAIL**: "Playwright installed but no config found. Run `npx playwright init` to create playwright.config.ts" | | Missing | Missing | **FAIL**: "Playwright not installed. Run `npm init playwright@latest` to set up E2E testing" | | Found | Missing | **Proceed** with warning: "Playwright config found but package not in package.json (global install?)" |

Store `PW_CONFIG` path for later use.

Step 3: Read spec.md — AC Extraction

Parse the increment's spec.md to extract acceptance criteria:

# Extract ACs: matches both [ ] and [x] checkboxes
grep -E '^\s*-\s*\[[ x]\]\s*\*\*AC-' .specweave/increments/<id>/spec.md

**Parsing algorithm**:

1. Read `.specweave/increments/<id>/spec.md` 2. For each line matching `- [[ x]] **AC-USx-xx**: <text>`:

• Extract AC-ID (e.g., `AC-US1-01`)
• Extract description text (the Given/When/Then or plain text after the colon)
• Derive parent US-ID from AC prefix (e.g., `AC-US1-01` → `US-001`)
• Flag `hasGWT` if text contains "Given" AND "When" AND "Then"

3. Group ACs by parent US-ID 4. Detect journey sequences: ACs under the same US that describe sequential steps on the same page

**Edge cases**:

• **No ACs found**: Output "No acceptance criteria found in spec.md — nothing to generate" and exit cleanly
• **ACs without Given/When/Then**: Generate a test stub with `// TODO: AC text does not follow GWT format — implement test manually`
• **Duplicate AC-IDs**: Warn, append `-dup1` suffix to the test name

Store the parsed result as a structured list for subsequent steps.

---

Step 4: Generate Mode (`--generate`)

**Goal**: Create Playwright test files from extracted ACs.

4a. Determine Output Directory

# Read testDir from playwright config, default to e2e/
TEST_DIR=$(grep -oP "testDir:\s*['\"]([^'\"]+)" "$PW_CONFIG" | head -1 | sed "s/testDir:\s*['\"]//")
TEST_DIR="${TEST_DIR:-e2e}"
mkdir -p "$TEST_DIR"

4b. Generate Test Files

For each user story, create `{TEST_DIR}/us-{NNN}.spec.ts`:

**Template for standard ACs** (one test per AC):

import { test, expect } from '@playwright/test';

test.describe('US-001: <User Story Title>', () => {
  test('AC-US1-01: <AC description summary>', async ({ page }) => {
    // Given: <given clause>
    // When: <when clause>
    // Then: <then clause>

    // TODO: Implement test steps
    // AC text: <full AC text>
  });

  test('AC-US1-02: <AC description summary>', async ({ page }) => {
    // ...
  });
});

**Template for journey ACs** (grouped into one test):

When multiple ACs under the same US describe sequential steps (e.g., "user sees form" → "user submits form" → "user sees confirmation"), group them:

test('AC-US1-01 → AC-US1-03: <journey description>', async ({ page }) => {
  // --- AC-US1-01: <description> ---
  // Given/When/Then steps...

  // --- AC-US1-02: <description> ---
  // Given/When/Then steps...

  // --- AC-US1-03: <description> ---
  // Given/When/Then steps...
});

4c. Post-Generate Summary

Output:

Generated E2E tests:
  {TEST_DIR}/us-001.spec.ts (3 ACs: AC-US1-01, AC-US1-02, AC-US1-03)
  {TEST_DIR}/us-002.spec.ts (2 ACs: AC-US2-01, AC-US2-02)

Total: 5 tests across 2 files
Next: Implement test steps, then run with sw:e2e --run <id>

---

Step 5: Run Mode (`--run`)

**Goal**: Execute Playwright tests and produce AC-mapped `e2e-report.json`.

5a.