@athenaflow/plugin-e2e-test-builder 2.0.9 → 2.0.10

package/dist/2.0.8/claude/plugin/skills/plan-test-coverage/SKILL.md

@@ -1,116 +0,0 @@
----
-name: plan-test-coverage
-description: >
-  Use before writing specs or test code to decide what E2E coverage is needed first. It scans existing tests, inspects the target flow, finds coverage gaps, and produces a prioritized P0/P1/P2 plan with TC-IDs. Use it for requests like "what tests do I need", "coverage gaps", or "what TC-IDs are missing". It does not write detailed specs or executable tests.
-allowed-tools: Read Glob Grep Task mcp__browser__ping mcp__browser__navigate mcp__browser__find mcp__browser__get_element mcp__browser__get_form mcp__browser__get_field mcp__browser__click mcp__browser__type mcp__browser__press mcp__browser__select mcp__browser__hover mcp__browser__drag mcp__browser__scroll mcp__browser__scroll_to mcp__browser__wheel mcp__browser__snapshot mcp__browser__screenshot mcp__browser__go_back mcp__browser__go_forward mcp__browser__reload mcp__browser__list_pages mcp__browser__close_page
----
-
-# Plan Test Coverage
-
-Plan what E2E tests to write for a feature by analyzing existing test coverage and doing a quick site inspection.
-
-## Workflow
-
-1. **Parse input** — extract the target URL and feature area from: $ARGUMENTS
-
-2. **Check existing test coverage**:
-   - Search for existing test files related to the feature:
-     ```
-     Grep for feature keywords in **/*.spec.ts, **/*.test.ts
-     ```
-   - Identify what's already covered and what's missing
-   - Note existing TC-IDs for the feature area to avoid conflicts
-
-3. **Quick site inspection** (lightweight, not full exploration):
-   - Follow the `agent-web-interface-guide` skill's browsing patterns (orient before acting, use `list_pages` for session awareness, close only pages you opened)
-   - Navigate to the URL in a dedicated page
-   - Use `find` to catalog the main interactive elements
-   - Use `get_form` or `get_field` if the page has forms worth covering
-   - Identify the key user flows visible on the page
-   - Close only the page you opened when done; do not rely on a session-wide close
-
-4. **Identify test categories** — for the feature, determine tests needed across:
-   - **Critical path** — core happy path that must never break
-   - **Input validation** — form fields, required fields, format constraints
-   - **Error states** — network errors, server errors, empty states
-   - **Edge cases** — boundary values, special characters, concurrent actions
-   - **Cross-feature** — interactions with other features (e.g., auth + checkout)
-   - **Accessibility** — keyboard navigation, screen reader support, focus management
-   - **Visual regression** — layout consistency, responsive breakpoints (375px, 768px, 1280px)
-   - **Performance** — loading states, lazy loading, large data sets
-   - **Network errors** — server 500s, timeouts, offline behavior
-
-   Not all categories apply to every project. Include Accessibility, Visual Regression, and Cross-Browser sections only when the project has explicit requirements, tooling, or configuration for them. Omit them from the output plan if not relevant — a focused plan is more useful than a padded one.
-
-5. **Prioritize** — rank tests by:
-   - **P0 (Must have)**: Core user journey, auth flows, data corruption prevention. Blocks revenue/signups if broken.
-   - **P1 (Should have)**: Input validation, common error paths, accessibility basics (keyboard navigation, form labels)
-   - **P2 (Nice to have)**: Edge cases, visual regression, performance scenarios, cross-browser specifics, rare error paths
-
-6. **Output test plan**:
-
-```markdown
-## Test Coverage Plan: <Feature>
-
-**URL:** <url>
-**Date:** <date>
-**Existing coverage:** <N tests already exist / none>
-
-### Already Covered
-- TC-FEATURE-001: <description> (in `tests/feature.spec.ts`)
-- ...
-
-### Proposed New Tests
-
-#### P0 — Critical Path
-| TC-ID | Description | Why Critical |
-|-------|-------------|-------------|
-| TC-FEATURE-010 | Happy path: user completes full flow | Core revenue path |
-
-#### P1 — Validation & Errors
-| TC-ID | Description | Why Important |
-|-------|-------------|--------------|
-| TC-FEATURE-020 | Submit with empty required fields | Common user error |
-
-#### P2 — Edge Cases
-| TC-ID | Description | Notes |
-|-------|-------------|-------|
-| TC-FEATURE-030 | Special characters in search input | Unicode handling |
-
-#### Accessibility (include if project has accessibility requirements or WCAG compliance goals)
-| TC-ID | Description | WCAG Criterion |
-|-------|-------------|----------------|
-| TC-FEATURE-A01 | Keyboard-only navigation through flow | 2.1.1 Keyboard |
-| TC-FEATURE-A02 | Form errors announced to screen readers | 1.3.1 Info and Relationships |
-
-#### Visual Regression (if project has visual testing setup)
-| TC-ID | Description | Viewport |
-|-------|-------------|----------|
-| TC-FEATURE-V01 | Layout consistency at mobile width | 375x812 |
-
-#### Cross-Browser Matrix (include if project runs tests across multiple browsers)
-| Browser | Priority | Reason |
-|---------|----------|--------|
-| Chromium | P0 | Primary target |
-| Firefox | P1 | Second largest desktop share |
-| WebKit/Safari | P1 | Required for iOS users |
-
-### Recommended Order
-1. Write P0 tests first (N tests)
-2. Then P1 validation + accessibility basics (N tests)
-3. P2 edge cases, visual regression, and performance as time allows
-
-### Next Steps
-- Invoke the `generate-test-cases` skill with the target URL and journey for detailed test specs
-- Invoke the `write-test-code` skill to implement the tests
-```
-
-## Example Usage
-
-```
-Claude Code: /plan-test-coverage https://myapp.com/checkout Checkout flow
-Codex: $plan-test-coverage https://myapp.com/checkout Checkout flow
-
-Claude Code: /plan-test-coverage https://myapp.com/login Authentication
-Codex: $plan-test-coverage https://myapp.com/login Authentication
-```

package/dist/2.0.8/codex/plugin/.codex-plugin/plugin.json

@@ -1,15 +0,0 @@
-{
-  "name": "e2e-test-builder",
-  "version": "2.0.8",
-  "description": "Full-pipeline Playwright E2E test generation — explores your live site via browser, detects existing test conventions, plans coverage gaps, produces reviewed test specs, writes production-grade test code with quality gates, and stabilizes flaky tests",
-  "author": {
-    "name": "Athenaflow"
-  },
-  "skills": "./skills/",
-  "interface": {
-    "displayName": "E2E Test Builder",
-    "shortDescription": "Full-pipeline Playwright E2E test generation with browser exploration and quality gates",
-    "developerName": "Athenaflow",
-    "category": "Testing"
-  }
-}

package/dist/2.0.8/codex/plugin/package.json

@@ -1,9 +0,0 @@
-{
-  "name": "@athenaflow/plugin-e2e-test-builder",
-  "version": "2.0.8",
-  "description": "Full-pipeline Playwright E2E test generation — explores your live site via browser, detects existing test conventions, plans coverage gaps, produces reviewed test specs, writes production-grade test code with quality gates, and stabilizes flaky tests",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  }
-}

package/dist/2.0.8/codex/plugin/skills/add-e2e-tests/SKILL.md

@@ -1,217 +0,0 @@
----
-name: add-e2e-tests
-description: >
-  THE DEFAULT ENTRY POINT for all Playwright / E2E test work. This skill should be used FIRST
-  whenever the user wants to add, create, or set up end-to-end tests for any feature, page, or
-  application. Runs the full pipeline: analyze codebase, explore the live site, plan coverage,
-  generate TC-ID specs, run quality-gate reviews, write production-grade test code, and execute.
-  Delegates to sub-skills (analyze-test-codebase, plan-test-coverage, generate-test-cases,
-  review-test-cases, write-test-code, review-test-code, fix-flaky-tests) internally — do NOT
-  skip to sub-skills directly unless the user explicitly requests a narrow activity.
-  Iterative and resumable via tracker file. Uses subagent delegation to save context.
-user-invocable: true
-argument-hint: "<url> <feature to test>"
-allowed-tools: Read Write Edit Glob Grep Bash Task
----
-
-# Add E2E Tests
-
-Go from zero to passing Playwright tests for the target feature in one interactive session.
-
-## Input
-
-Parse the target URL and feature description from: $ARGUMENTS
-
-Derive a **feature slug** from the feature description (e.g., "Login flow" → `login`, "Checkout with payment" → `checkout`). Use this slug for file naming throughout.
-
-## Session Protocol
-
-### 1. Orient: Understand the Project, the Product, and Your Capabilities
-
-Before planning any work, build deep situational awareness. This step determines the quality of everything that follows — rushed orientation leads to missed test cases and wasted effort.
-
-**Check for existing progress:**
-- If `e2e-tracker.md` exists in the project root, read it and resume from where you left off — skip to **step 2 (Plan)** with the remaining work.
-- If no tracker exists, this is a fresh start. Proceed with orientation below.
-
-#### First: create initial tasks and tracker
-
-As soon as you parse the user's request:
-
-1. **Create the tracker** — write `e2e-tracker.md` with the goal (URL, feature, slug) and a skeleton plan.
-2. **Create high-level tasks** for the work ahead — analyze codebase, explore the product, plan coverage, generate test specs, write tests, verify tests.
-
-These are your starting skeleton. As you work through orientation and discover the actual shape of the work, refine both the tasks and the tracker — break tasks into granular sub-tasks, add new ones, remove ones that don't apply.
-
-Treat the task list as a visible milestone log. Keep it concise, but update it continuously. Do not leave broad tasks open until the end and then mark everything complete in one batch.
-
-#### 1a. Understand the codebase
-
-- Does a Playwright config exist (`playwright.config.{ts,js,mjs}`)? If not, you will need to scaffold one (see Scaffolding section).
-- Are there existing tests? What conventions do they follow — naming, locators, fixtures, page objects, auth?
-- Load the `analyze-test-codebase` skill and follow its methodology.
-
-#### 1b. Understand the product
-
-This is the most important part of orientation. You cannot write good tests for a product you don't understand.
-
-- **Read existing test cases** — if `test-cases/*.md` files exist, read them to understand what journeys have been mapped. Look at what's covered AND what's missing.
-- **Browse the actual product** — load the `agent-web-interface-guide` skill and use the browser MCP tools to walk through the feature you're testing. Don't just skim the page — interact with it as a user would: fill forms, click buttons, trigger validation, navigate between pages, check error states.
-- **Map the user journey in detail** — understand the complete flow: entry points, happy paths, error paths, edge cases, what happens with invalid input, what happens when the user goes back, what conditional UI exists.
-
-Why this matters: absent explicit exploration, agents tend to write tests based on assumptions about how a product works rather than how it actually works. The result is tests that target imaginary behavior or miss critical real behavior. Spending time here prevents both.
-
-#### 1c. Know your skills
-
-You have access to specialized skills that contain deep domain knowledge. Load the relevant skill before performing each activity — skills prevent improvisation and encode best practices.
-
-| Activity | Skill |
-|----------|-------|
-| Analyzing test setup, config, conventions | `analyze-test-codebase` |
-| Deciding what to test, coverage gaps, priorities | `plan-test-coverage` |
-| Opening a URL, browsing, using browser MCP tools | `agent-web-interface-guide` |
-| Creating TC-ID specs from site exploration | `generate-test-cases` |
-| Reviewing TC-ID specs before implementation | `review-test-cases` |
-| Writing, editing, or refactoring test code | `write-test-code` |
-| Reviewing test code before execution signoff | `review-test-code` |
-| Debugging test failures, checking stability | `fix-flaky-tests` |
-
-Before doing a substantial activity, load the skill that covers that activity so you can follow its workflow rather than improvising.
-
-#### 1d. Update the tracker with orientation findings
-
-After orienting, update the tracker with what you learned about the codebase and product, conventions discovered, and your refined plan. The tracker must always answer these four questions for anyone reading it cold:
-
-1. What is the goal?
-2. What has been done?
-3. What is remaining?
-4. What should I do next?
-
-See [references/tracker-template.md](references/tracker-template.md) for a concrete template.
-
-### 2. Plan: Refine Tasks Into Granular Checkpoints
-
-By now you have initial tasks and a tracker from step 1. Refine tasks into granular checkpoints. The plan should flow from what you learned during orientation, not from a fixed template.
-
-#### Task granularity
-
-Think in small checkpoints, not big phases. Each task should represent a concrete, verifiable unit of progress.
-
-Too coarse: "Analyze codebase", "Write tests", "Verify tests"
-
-Right granularity:
-- "Read playwright.config.ts — extract baseURL, testDir, projects"
-- "Read 2 existing test files — identify locator strategy and naming pattern"
-- "Write conventions report to e2e-plan/conventions.md"
-- "Navigate to /login — catalog all form fields, buttons, and validation messages"
-- "Submit login form empty — record all validation error messages and their positions"
-- "Submit login with invalid email format — record inline validation behavior"
-- "Write TC-LOGIN-001: happy path login with valid credentials"
-- "Write TC-LOGIN-002: login with empty email shows required field error"
-- "Run login.spec.ts and record full output"
-- "Fix TC-LOGIN-003: selector not found — browse page and re-extract selector"
-- "Re-run login.spec.ts — verify fix didn't break other tests"
-- "Check all TC-IDs from spec are present in test files"
-
-**Never be conservative.** More tasks is better than fewer. If you discover new work mid-session (a test fails, a selector changed, a form has unexpected validation), add tasks dynamically. The task list is a living document that reflects the real state of the work.
-
-Create tasks for verification steps too (running tests, checking coverage, browsing to confirm selectors), not just implementation.
-
-Update task status as each checkpoint completes. A good pattern is: finish exploration and mark it complete, finish coverage/spec work and mark it complete, finish implementation and mark it complete, then finish review/execution and mark it complete. Do not keep all milestones open until session end.
-
-### 3. Execute
-
-Work through your tasks. Load the relevant skill before each activity.
-
-#### Planning uses the browser heavily
-
-When planning what to test (coverage planning, test case generation), use the browser extensively. Don't just catalog elements — interact with the product to discover:
-- What validation messages appear for each field?
-- What happens when you submit with missing data?
-- What error states exist (network errors, empty states, permission errors)?
-- What does the flow look like end-to-end, not just page-by-page?
-- What edge cases exist (special characters, long inputs, rapid clicks)?
-- What UI changes conditionally (loading states, disabled buttons, progressive disclosure)?
-
-Every test case you generate should trace back to something you actually observed or deliberately triggered in the browser. This is how you avoid introducing useless test cases (testing imaginary behavior) and avoid missing important ones (behavior you didn't think to check).
-
-#### Subagent delegation
-
-Delegate heavy browser exploration and test writing to subagents when that saves context for orchestration, verification, and debugging. When delegating:
-- Pass the relevant file paths (conventions, coverage plan, test specs)
-- Instruct the subagent to invoke the appropriate skill (subagents inherit access to plugin skills)
-- Specify concrete output expectations (file path, format, TC-ID conventions)
-
-#### Quality gates
-
-Two review gates and a test execution checkpoint are mandatory during execution. The review gates are review-only — they produce findings but do not modify files.
-
-**Gate 1: Review test case specs** (after `generate-test-cases`, before `write-test-code`)
-1. Load the `review-test-cases` skill and run it against `test-cases/<feature>.md`
-2. If verdict is **NEEDS REVISION** — address all blockers in the spec before proceeding to implementation
-3. If verdict is **PASS WITH WARNINGS** — address warnings if quick, otherwise note them and proceed
-4. Record the review verdict in the tracker
-
-**Gate 2: Review test code** (after `write-test-code`, before final test execution)
-1. Load the `review-test-code` skill and run it against the implemented test files
-2. If verdict is **NEEDS REVISION** — fix all blockers before running tests for signoff
-3. If verdict is **PASS WITH WARNINGS** — fix warnings that affect stability, proceed with execution
-4. Record the review verdict in the tracker
-
-**Checkpoint: Test execution**
-1. Run the tests: `npx playwright test <file> --reporter=list 2>&1`
-2. Record full output — green test output is the only proof of correctness
-3. If tests fail, load the `fix-flaky-tests` skill and follow its structured diagnostic approach. Do not guess-and-retry.
-4. Maximum 3 fix-and-rerun cycles per test. If stuck after 3 cycles, record the diagnostic output in the tracker and move on.
-
-**Test execution and coverage checks must never be delegated to subagents.** Run `npx playwright test` directly and record the output.
-
-#### Update the tracker as you work
-
-Do not wait until session end. After each meaningful chunk of progress (completing a step, discovering a blocker, producing an artifact), update the tracker. If your context window resets, only what's in the tracker survives.
-
-Keep the tracker and task list synchronized. If you record progress in the tracker, update the corresponding task status in the same phase of work.
-
-#### Error recovery
-
-If infrastructure failures occur (browser MCP unavailable, clone failures, npm install errors), see [references/error-recovery.md](references/error-recovery.md) for diagnostic steps. General pattern: diagnose, attempt one known fix, if still stuck record in tracker and ask the user.
-
-### 4. End of Session
-
-Before exiting:
-1. Ensure the tracker reflects all progress, discoveries, and blockers from this session
-2. Write clear instructions for what the next session should do
-3. If all work is complete and all tests pass with full TC-ID coverage: write `<!-- E2E_COMPLETE -->` as the last line of the tracker
-4. If an unrecoverable blocker prevents progress: write `<!-- E2E_BLOCKED: reason -->` as the last line
-
-Do not write terminal markers prematurely. Only after you are confident the work is truly done or truly stuck.
-
-## Scaffolding
-
-If Playwright is not set up in the target project, follow the procedure in [references/scaffolding.md](references/scaffolding.md) to clone the boilerplate, merge configuration, and install dependencies. Log all scaffolding steps in the tracker.
-
-## Authentication
-
-If the target feature requires login, follow [references/authentication.md](references/authentication.md). Key rule: never hardcode credentials — use environment variables or `storageState`.
-
-## Principles
-
-- **Skills carry the knowledge** — load the relevant skill before each activity; do not improvise
-- **Subagent-driven** — delegate heavy browser and writing work to subagents to save context
-- **Follow existing conventions** — match the project's test style, not a generic template
-- **Traceable** — every test links back to a TC-ID from the spec
-- **Use what the project provides** — if the scaffolded boilerplate includes Page Object Models (BasePage, pages/), path aliases (tsconfig paths), or utility modules, USE them in generated tests. Do not ship infrastructure that tests ignore. If a boilerplate file is unused after test generation, either integrate it or remove it — dead code in test infrastructure causes confusion.
-- **No arbitrary waits** — use Playwright's built-in auto-wait and event-driven waits
-- **API before UI for setup** — use API calls (`request` fixture) for test data; reserve UI for what you are verifying
-- **Test failures, not just success** — every feature needs error path coverage
-- **Artifacts live in standard locations** — `e2e-plan/` for analysis, `test-cases/` for specs, project test dir for test files
-
-## Example Usage
-
-```
-Claude Code: /add-e2e-tests https://myapp.com/checkout Checkout flow with cart, shipping, and payment
-Codex: $add-e2e-tests https://myapp.com/checkout Checkout flow with cart, shipping, and payment
-
-Claude Code: /add-e2e-tests https://myapp.com/login User authentication including social login
-Codex: $add-e2e-tests https://myapp.com/login User authentication including social login
-```

package/dist/2.0.8/codex/plugin/skills/add-e2e-tests/agents/claude.yaml

@@ -1 +0,0 @@
-{}

package/dist/2.0.8/codex/plugin/skills/add-e2e-tests/references/error-recovery.md

@@ -1,43 +0,0 @@
-# Error Recovery for Infrastructure Failures
-
-When infrastructure failures occur during E2E test building, follow the general pattern: diagnose, attempt one known fix, if still stuck record in tracker and ask the user.
-
-## Browser MCP unavailable
-
-The browser MCP server (`agent-web-interface`) must be running for site exploration.
-
-1. Verify the MCP server is configured in the project (check `.mcp.json` or plugin config).
-2. Ask the user to confirm the MCP server is running or to restart it.
-3. If unreachable after user intervention, mark the session as blocked: `<!-- E2E_BLOCKED: browser MCP server unreachable -->`.
-
-## Boilerplate clone fails
-
-When `git clone git@github.com:lespaceman/playwright-typescript-e2e-boilerplate.git` fails:
-
-1. Check if SSH keys are configured — the error will usually indicate `Permission denied (publickey)`.
-2. Fall back to HTTPS: `git clone https://github.com/lespaceman/playwright-typescript-e2e-boilerplate.git`.
-3. If both fail, ask the user to verify network access and GitHub authentication.
-
-## npm install fails
-
-1. Check the Node.js version — Playwright requires Node 18+. Run `node --version`.
-2. Clear the npm cache: `npm cache clean --force`.
-3. Check for lockfile conflicts — if both `package-lock.json` and `yarn.lock` exist, ask the user which package manager to use.
-4. If dependency resolution fails, try `npm install --legacy-peer-deps` as a fallback.
-
-## Playwright browser install fails
-
-When `npx playwright install --with-deps chromium` fails:
-
-1. Try installing just chromium without system deps: `npx playwright install chromium`.
-2. Check permissions — on Linux, system dependency installation may require sudo.
-3. If behind a corporate proxy, ask the user for proxy configuration.
-4. As a last resort, ask the user to run the install command manually and confirm when done.
-
-## General pattern
-
-For any infrastructure failure not listed above:
-
-1. **Diagnose** — read the error message carefully, check logs, identify the root cause.
-2. **Attempt one known fix** — apply the most likely solution based on the error.
-3. **If still stuck** — record the full error output and diagnostic steps taken in the tracker, then ask the user for help. Do not loop through multiple speculative fixes.

package/dist/2.0.8/codex/plugin/skills/add-e2e-tests/references/tracker-template.md

@@ -1,53 +0,0 @@
-# Tracker Template: e2e-tracker.md
-
-Use this as a starting template when creating the tracker file. Adapt sections as needed.
-
----
-
-```markdown
-# E2E Test Tracker
-
-## Goal
-
-- **URL:** https://myapp.com/checkout
-- **Feature:** Checkout flow with cart, shipping, and payment
-- **Slug:** checkout
-
-## Progress
-
-### Session 1 — 2026-04-01
-
-- Analyzed codebase: Playwright 1.42, TypeScript, existing auth fixture in `tests/fixtures/auth.ts`
-- Browsed checkout flow: 4-step wizard (cart review, shipping, payment, confirmation)
-- Discovered 3 form validation states per step
-- Generated test spec: `test-cases/checkout.md` with TC-CHECKOUT-001 through TC-CHECKOUT-012
-- Review gate passed with warnings (TC-CHECKOUT-008 needs clarification on coupon edge case)
-
-### Session 2 — 2026-04-02
-
-- Wrote `tests/checkout.spec.ts` covering TC-CHECKOUT-001 through TC-CHECKOUT-012
-- Code review gate passed
-- Ran tests: 10/12 passing, 2 failing (TC-CHECKOUT-006: selector stale, TC-CHECKOUT-011: timeout)
-- Fixed TC-CHECKOUT-006: updated selector from `.price` to `[data-testid="cart-total"]`
-- Fixed TC-CHECKOUT-011: added `waitForResponse` before assertion
-
-## Remaining
-
-- Re-run full suite to confirm fixes
-- Verify TC-ID coverage: all 12 specs should map to test code
-
-## Next Steps
-
-- Run `npx playwright test tests/checkout.spec.ts --reporter=list` and record output
-- If all green, mark complete
-- If failures remain, diagnose with `fix-flaky-tests` skill
-
-<!-- E2E_COMPLETE -->
-```
-
----
-
-**Terminal markers** (write as the last line of the tracker when appropriate):
-
-- `<!-- E2E_COMPLETE -->` — all tests pass, all TC-IDs covered, work is done
-- `<!-- E2E_BLOCKED: reason -->` — unrecoverable blocker prevents further progress (e.g., `<!-- E2E_BLOCKED: login requires 2FA token we cannot automate -->`)

package/dist/2.0.8/codex/plugin/skills/fix-flaky-tests/SKILL.md

@@ -1,160 +0,0 @@
----
-name: fix-flaky-tests
-description: >
-  This skill should be used when a Playwright test is failing, flaky, timing out, or behaving
-  inconsistently. It provides structured root cause analysis for: stabilizing intermittent tests,
-  debugging timeouts ("Test timeout of 30000ms exceeded"), fixing race conditions, investigating
-  local-vs-CI divergence, running repeated stability checks (--repeat-each).
-  IMPORTANT: If running tests with --repeat-each, --retries, or multiple times to check stability,
-  STOP and load this skill first — it has structured root cause analysis that prevents brute-force
-  approaches. Triggers: "stabilize", "intermittent", "flaky", "keeps failing", "fails in CI",
-  "timeout on", "race condition", "run N times to check stability", "verify tests are stable".
-  NOT for writing new tests (use write-test-code) or analyzing setup (use analyze-test-codebase).
-allowed-tools: Read Write Edit Bash Glob Grep Task
----
-
-# Fix Flaky Tests
-
-Systematically diagnose and fix intermittent Playwright test failures using root cause analysis. A flaky test is worse than no test — it trains teams to ignore failures.
-
-## Input
-
-Parse the test file path or test name from: $ARGUMENTS
-
-If no argument provided, ask: "Which test file or test name is flaky?"
-
-## Workflow
-
-### Step 1: Reproduce and Classify
-
-1. **Read the test file** to understand what it tests and how
-2. **Run the test multiple times** to observe the failure pattern:
-   ```bash
-   npx playwright test <file> --repeat-each=5 --reporter=list 2>&1
-   ```
-3. **Run in isolation** if it passed above — it may only fail with other tests:
-   ```bash
-   npx playwright test --reporter=list 2>&1
-   ```
-4. **Classify the failure** into one of these root cause categories:
-
-| Category | Symptoms |
-|----------|----------|
-| **Timing** | Timeout errors, "element not found", "not visible yet" |
-| **State leakage** | Passes alone, fails when run with other tests |
-| **Data dependency** | Fails when expected data doesn't exist or has changed |
-| **Race condition** | Action fires before page is ready (hydration, animation) |
-| **Selector fragility** | Element found but wrong one, or `.first()` picks different element |
-| **Environment** | Passes locally, fails in CI (viewport, speed, resources) |
-
-### Step 2: Root Cause Analysis
-
-Investigate based on the classification:
-
-**Timing issues:**
-- Look for assertions immediately after actions with no wait for the resulting state change
-- Check if the test asserts before an API response arrives — search for missing `waitForResponse`
-- Look for animations/transitions that affect element state (CSS transitions, skeleton screens)
-- Check for `waitForTimeout` being used as a "fix" — this is a symptom, not a cure
-- Check if `networkidle` or `load` waitUntil would help for navigation
-
-**State leakage:**
-- Run the failing test alone: `npx playwright test --grep "<test name>"`
-- Check if tests share mutable state: global variables, database rows, cookies, localStorage
-- Look for missing cleanup in `afterEach`/`afterAll`
-- Check if `storageState` bleeds between tests or test files
-- Check for test data created by one test that another test depends on
-
-**Race conditions:**
-- Identify the race: what two things are happening concurrently?
-- Check for click handlers that fire before JavaScript hydration completes
-- Look for optimistic UI updates that revert on API response
-- Check for actions during navigation transitions (click during page load)
-- Look for double-clicks or rapid interactions that trigger duplicate actions
-
-**Selector fragility:**
-- Navigate to the page in the browser and verify the selector currently matches the intended element
-- Check if the selector matches multiple elements — `.first()` or `.nth()` is a smell
-- Look for dynamically generated IDs, classes, or attributes
-- Check for conditional rendering that changes element order or presence
-- Verify locators against current DOM structure using `find` and `get_element`
-
-**Environment issues:**
-- Compare CI viewport size vs local — element may be off-screen in CI
-- Check for timezone-dependent assertions (dates, timestamps)
-- Check for locale-dependent formatting (numbers, currency)
-- Check if CI has slower network/CPU affecting timing
-- Look for third-party scripts (analytics, chat widgets) that load differently in CI
-
-### Step 3: Apply the Correct Fix
-
-Use the right fix pattern for the diagnosed root cause. **Never apply a fix without understanding the cause.** See [references/fix-patterns.md](references/fix-patterns.md) for full code examples.
-
-| Category | Principle |
-|----------|-----------|
-| **Timing** | Replace sleeps with event-driven waits (`waitForResponse`, auto-retrying assertions) |
-| **State isolation** | Unique data per test, API-based reset in `beforeEach`, no shared mutable state |
-| **Race condition** | Use `Promise.all` for action + expected response; wait for hydration before interaction |
-| **Selector** | Scope locators to containers with unique content; avoid `.first()` and position-dependent selectors |
-| **Environment** | Explicit viewport, timezone-agnostic assertions, block interfering third-party scripts |
-
-### Step 4: Verify the Fix
-
-1. **Run the test 5+ times** to confirm stability:
-   ```bash
-   npx playwright test <file> --repeat-each=5 --reporter=list 2>&1
-   ```
-2. **Run with the full test suite** to verify no state leakage:
-   ```bash
-   npx playwright test --reporter=list 2>&1
-   ```
-3. If still flaky → return to Step 2 with the new failure output. The initial classification may have been wrong.
-4. **Maximum 3 fix-and-rerun cycles.** If the test is still flaky after 3 attempts, stop and report the diagnostic findings (root cause hypothesis, fixes attempted, remaining failure output) so the user can decide next steps. Do not continue looping.
-
-### Step 5: Summarize
-
-Report:
-1. **Root cause** — what made the test flaky and why
-2. **Fix applied** — what changed and why this fix addresses the root cause
-3. **Verification** — how many consecutive runs passed
-4. **Prevention** — what pattern to follow in future tests to avoid this class of flakiness
-
-## Flakiness Checklist (Less Obvious Causes)
-
-When the standard categories don't fit, check these:
-
-- [ ] **Viewport size** — element off-screen in CI (smaller viewport)
-- [ ] **Font rendering** — text matching fails due to font differences across OS
-- [ ] **Timezone** — date/time assertions fail in different timezones
-- [ ] **Locale** — number/currency formatting differs (1,000 vs 1.000)
-- [ ] **Third-party scripts** — analytics/chat widgets change DOM or block clicks
-- [ ] **Cookie consent banners** — overlay blocks click targets
-- [ ] **Feature flags** — different features enabled in different environments
-- [ ] **Database state** — shared test database with stale or conflicting data
-- [ ] **Parallel execution** — tests interfere when run in parallel workers
-- [ ] **Browser caching** — cached responses differ from fresh ones
-- [ ] **Service workers** — intercepting requests differently than expected
-- [ ] **Lazy loading** — elements not yet in DOM when test tries to interact
-
-## Anti-Patterns: What is NOT a Fix
-
-These mask the problem. Never apply them without a real fix:
-
-| "Fix" | Why It's Wrong | Real Fix |
-|-------|---------------|----------|
-| `waitForTimeout(3000)` | Hides timing race, will break under load | Wait for the specific event |
-| `.first()` added | Hides selector ambiguity | Narrow the selector |
-| Increased timeout to 30s | Hides missing wait or slow setup | Find what you're actually waiting for |
-| `test.skip()` | Ignoring the problem | Diagnose and fix |
-| `retries: 3` without fix | Masks real failures, wastes CI time | Fix the root cause, then keep retries as safety net |
-| `{ force: true }` | Bypasses actionability checks, hides overlapping elements or disabled state | Find and fix the actionability issue: wait for overlay to disappear, scroll element into view, or wait for enabled state |
-| `try/catch` swallowing errors | Test passes but doesn't verify anything | Fix the assertion |
-
-## Multiple Flaky Tests
-
-When a suite has several flaky tests:
-
-1. **Triage first.** Run the full suite once and group failures by root cause category (timing, state leakage, etc.). Shared root causes (broken fixture, leaking state) should be fixed once, not per-test.
-2. **Fix shared infrastructure issues first.** A bad `beforeEach`, a leaking `storageState`, or a missing cleanup can cause many tests to fail. One fix resolves many failures.
-3. **Split independent fixes across subagents** when the fix scopes do not overlap (different test files, no shared fixtures). Pass each subagent the test file path, this diagnostic workflow, and the root cause classification table.
-4. The 3 fix-and-rerun cycle limit applies **per test**, not globally.