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

package/dist/2.0.9/codex/plugin/skills/review-test-code/SKILL.md

@@ -1,189 +0,0 @@
----
-name: review-test-code
-description: >
-  Quality review of Playwright test code before final execution signoff. This skill should be used
-  when implementation review of executable Playwright tests is needed, not for diagnosis of runtime flakiness.
-  Triggers: "review test code", "review Playwright tests", "check test quality",
-  "audit test implementation", "review my tests before merging", "check test code for issues",
-  "review e2e tests", "code review Playwright", "are my tests stable",
-  "check for brittle selectors", "review before running tests". Quality gate
-  after write-test-code — catches brittle selectors, force:true misuse, networkidle overuse, Tailwind
-  utility class selectors, exact numeric assertions, missing teardown, parallel-unsafe mutations,
-  hardcoded data, missing assertions, test coupling, and convention divergence. Review-only — does NOT
-  rewrite tests, does NOT run tests. Use fix-flaky-tests for fixing, write-test-code for rewriting.
-allowed-tools: Read Glob Grep Task
----
-
-# Review Test Code
-
-Review Playwright test code for stability, correctness, and adherence to project conventions before final execution signoff. This is a quality gate — catch structural issues in code before running tests, not after flaky failures.
-
-## Input
-
-Parse the test file path or directory from: $ARGUMENTS
-
-If no argument provided, search for recently modified `*.spec.ts` or `*.test.ts` files and review those.
-
-## Workflow
-
-### Step 1: Load Context
-
-1. Read the test file(s) to review
-2. Read project conventions for comparison:
-   - `playwright.config.ts` or `playwright.config.js` — extract `baseURL`, `testDir`, projects, timeouts, `fullyParallel`, `workers`
-   - 2-3 existing test files (not the ones under review) to establish the project's conventions
-   - `e2e-plan/conventions.md` if it exists
-3. Read the corresponding test case spec (`test-cases/<feature>.md`) if it exists — needed for traceability check
-4. Note the project's locator strategy, fixture patterns, auth approach, and naming conventions
-
-### Step 2: Run the Review Checklist
-
-Evaluate the test code against each criterion. Track findings by severity:
-
-- **BLOCKER** — will cause test failures or false passes (missing assertions, wrong selectors, broken isolation)
-- **WARNING** — will cause flakiness or maintenance burden (brittle selectors, arbitrary waits, poor structure)
-- **SUGGESTION** — style or convention improvement (naming, organization, minor readability)
-
-#### 2a. Locator Quality
-
-| Check | What to Look For |
-|-------|-----------------|
-| Semantic locators preferred | `getByRole`, `getByLabel`, `getByPlaceholder` over CSS selectors |
-| No fragile positional selectors | `.first()`, `.nth()`, `.last()` without documented justification |
-| No dynamic IDs or classes | Selectors containing generated hashes, UUIDs, or auto-incremented values |
-| No utility framework classes | Selectors must not contain Tailwind (`rounded-lg`, `flex`, `bg-*`), Bootstrap (`btn-primary`, `col-md-*`), or similar utility classes — these are styling, not identity |
-| Scoped to containers | Locators narrowed to `main`, `nav`, `[role="dialog"]` where needed |
-| No exact long text matches | Use regex with key words instead of full marketing copy |
-
-When a locator appears suspicious, delegate verification to a subagent (Task tool): instruct it to open the target URL, locate the element using the browser MCP tools (`find`, `get_element`), and report back whether the element exists and is unique.
-
-#### 2b. Waiting and Timing
-
-| Check | What to Look For |
-|-------|-----------------|
-| No `waitForTimeout()` | Arbitrary sleeps mask real timing issues |
-| Proper action-response waits | `waitForResponse` before asserting API-dependent UI |
-| Auto-retrying assertions used | `await expect(el).toBeVisible()` not `expect(await el.isVisible()).toBe(true)` |
-| Reasonable explicit timeouts | Custom timeouts (`{ timeout: 10000 }`) have a comment explaining why |
-| No `networkidle` overuse | `networkidle` is fragile; prefer specific response waits |
-
-#### 2c. Assertions
-
-| Check | What to Look For |
-|-------|-----------------|
-| Every test has assertions | No test blocks without `expect()` calls |
-| Assertions test user outcomes | Visible text, URL changes, element states — not internal state or CSS classes |
-| Assertions are specific | `toHaveText('Welcome, John')` not just `toBeVisible()` |
-| Error paths have assertions | Error scenario tests verify the error message, not just that "something happened" |
-| No exact server-computed values | Dashboard counters, totals, and aggregates must not assert exact numbers — use patterns, ranges, or seed data first |
-| No `toBeTruthy()` on locators | Use Playwright-specific matchers (`toBeVisible`, `toBeEnabled`, `toHaveText`) |
-
-#### 2d. Test Isolation and Structure
-
-| Check | What to Look For |
-|-------|-----------------|
-| No shared mutable state | Tests do not depend on execution order or modify shared variables |
-| Proper setup/teardown | `beforeEach`/`afterEach` for shared setup, not duplicated in each test |
-| AAA structure | Clear Arrange → Act → Assert sections (comments optional but structure required) |
-| No test coupling | Test B does not depend on side effects from Test A |
-| Auth handled correctly | `storageState` or fixture, not UI login in every test (unless testing login itself) |
-| Test data is unique | Uses `Date.now()`, factories, or unique IDs — not hardcoded shared data |
-| Parallel-safe (if `fullyParallel: true` or `workers` > 1 found in config) | Tests that create data must not assert on unscoped lists or counts — filter assertions to the specific data created. If parallelism is disabled, note as SUGGESTION rather than WARNING |
-| Data cleanup present | Tests that create persistent records (API POST/PUT) must have corresponding teardown (`afterEach`, fixture cleanup, or `globalTeardown`) |
-
-#### 2e. Convention Adherence
-
-| Check | What to Look For |
-|-------|-----------------|
-| TC-ID in test title | Every test has `TC-<FEATURE>-<NNN>: Description` format |
-| File naming matches project | Follows existing `*.spec.ts` or `*.test.ts` convention |
-| Import style matches project | Imports from project fixtures file if one exists, not raw `@playwright/test` |
-| baseURL used | `page.goto('/')` not `page.goto('https://example.com/')` |
-| POM pattern followed (if used) | Page objects for interactions, tests for assertions |
-| Consistent locator strategy | Same locator approach as existing tests |
-
-#### 2f. TC-ID Traceability
-
-If a test case spec file exists for this feature:
-- Verify every TC-ID from the spec has a corresponding test
-- Flag TC-IDs in the spec with no implementation
-- Flag tests with TC-IDs not present in the spec (orphaned tests)
-- Note: not every spec TC-ID must be implemented — but missing ones should be acknowledged
-
-#### 2g. Anti-Pattern Detection
-
-Flag any instances of these known anti-patterns:
-1. Raw CSS selectors where semantic locators would work
-2. `waitForTimeout()` used as a fix
-3. `.first()` / `.nth()` without justification
-4. Exact long text matches (fragile to copy changes)
-5. Login via UI in every test (should use storageState)
-6. UI clicks to set up test data (should use API)
-7. No error path tests in the suite
-8. Hardcoded test data
-9. Tests depending on execution order
-10. `expect(await el.isVisible()).toBe(true)` instead of `await expect(el).toBeVisible()`
-11. Missing `await` on Playwright calls (easy to miss, causes silent failures)
-12. `{ force: true }` on interactions without documented justification (masks actionability issues — overlapping elements, disabled state, not scrolled into view)
-13. `waitForLoadState('networkidle')` as default wait strategy — breaks on long-polling, WebSockets, analytics beacons; use specific `waitForResponse` or UI assertions instead
-14. CSS utility class selectors (Tailwind `rounded-lg`, `flex`, Bootstrap `btn-primary`, `col-md-*`) — styling classes are volatile, never use as selectors
-15. Asserting exact server-computed values (`toHaveText('12450')`) — use pattern matchers, ranges, or seed data to control expected values
-
-### Step 3: Produce the Review Report
-
-Output a structured review with this format:
-
-```markdown
-# Test Code Review: <file or feature>
-
-**Files reviewed:** <list>
-**Total tests:** <count>
-**Review date:** <date>
-
-## Verdict: PASS | PASS WITH WARNINGS | NEEDS REVISION
-
-## Blockers (<count>)
-- **<file>:<line>** `<test name>`: <issue description>
-
-## Warnings (<count>)
-- **<file>:<line>** `<test name>`: <issue description>
-
-## Suggestions (<count>)
-- **<file>:<line>**: <issue description>
-
-## Convention Divergences
-- <How this code differs from the project's established patterns>
-
-## TC-ID Traceability
-- **Implemented:** <count> / <total in spec>
-- **Missing from implementation:** <list of TC-IDs>
-- **Orphaned (no spec):** <list of TC-IDs>
-
-## Summary
-<2-3 sentences on overall code quality and what to address before test execution>
-```
-
-### Step 4: Verdict Rules
-
-- **PASS** — no blockers, 2 or fewer warnings. Proceed to test execution.
-- **PASS WITH WARNINGS** — no blockers, 3+ warnings. Can proceed but should address warnings for long-term stability.
-- **NEEDS REVISION** — 1+ blockers. Do not run tests expecting stable results until blockers are resolved.
-
-## Principles
-
-- **Review-only** — never modify test files; report findings for the author to act on
-- **Evidence over opinion** — cite specific file paths, line numbers, and code snippets when flagging issues
-- **Spot-check selectors** — delegate to a subagent with browser access to verify 2-3 suspicious locators against the live site
-- **Convention-first** — compare against the project's existing test patterns, not an abstract ideal
-- **Bounded output** — the review should be actionable and finite, not a full rewrite specification
-- **Severity matters** — a missing `await` is a blocker; a naming style preference is a suggestion
-
-## Example Usage
-
-```
-Claude Code: /review-test-code tests/e2e/login.spec.ts
-Codex: $review-test-code tests/e2e/login.spec.ts
-
-Claude Code: /review-test-code tests/e2e/
-Codex: $review-test-code tests/e2e/
-```

package/dist/2.0.9/codex/plugin/skills/review-test-code/agents/claude.yaml

@@ -1,3 +0,0 @@
-frontmatter:
-  argument-hint: "<path to test file or directory>"
-  user-invocable: true

package/dist/2.0.9/codex/plugin/skills/review-test-code/agents/openai.yaml

@@ -1,10 +0,0 @@
-interface:
-  display_name: "Review Playwright Test Code"
-  short_description: "Review Playwright test implementation for stability and correctness"
-  default_prompt: "Review this Playwright test implementation before execution and flag quality issues."
-
-dependencies:
-  tools:
-    - type: "mcp"
-      value: "agent-web-interface"
-      description: "Browser automation MCP used to verify selectors against the live site"

package/dist/2.0.9/codex/plugin/skills/write-test-code/SKILL.md

@@ -1,227 +0,0 @@
----
-name: write-test-code
-description: >
-  This skill should be used when writing, refactoring, or modifying Playwright E2E test code.
-  It covers creating test files from TC-ID specs, converting browser exploration results to
-  executable tests, refactoring locators or fixtures, adding API mocking, test data
-  setup/teardown, and parallel-safe isolation. Includes locator strategy hierarchy, auth setup
-  patterns, fixture design, teardown strategies, and network interception recipes.
-  Triggers: "write a test for", "add a test case", "refactor this locator", "add error path
-  tests", "convert specs to code", "add API mocking", "set up auth for tests".
-  NOT for: full pipeline from scratch (use add-e2e-tests), exploring live sites (use
-  agent-web-interface-guide), generating specs without code (use plan-test-coverage or
-  generate-test-cases), diagnosing flaky tests (use fix-flaky-tests).
-allowed-tools: Read Write Edit Bash Glob Grep Task
----
-
-# Write E2E Tests
-
-Write, refactor, or fix Playwright E2E tests. Convert browser exploration results or test case specifications into executable, stable test code.
-
-## Input
-
-Parse the test description or spec file path from: $ARGUMENTS
-
-## Workflow
-
-### 1. Understand the Request
-- Identify the user journey to test and success criteria
-- Identify preconditions (auth, seeded data, feature flags, env)
-- If a test case spec file path is provided, read it for TC-IDs and expected behaviors
-
-### 2. Inspect Repo Conventions (CRITICAL — before writing any code)
-- Search for `playwright.config.ts` / `playwright.config.js` — extract `baseURL`, `testDir`, projects
-- Search for existing tests, fixtures, page objects, locator patterns, test data modules
-- Read 2-3 existing test files to match the project's naming, structure, and locator strategy
-- Check for custom fixtures, POM patterns, auth setup (storageState, global setup)
-- Follow the project's existing style unless it clearly causes flakiness
-
-### 3. Verify Key Selectors Against the Live Site
-- If a test case spec file includes **Selectors observed**, use those as your starting point
-- If no spec or selectors are available, browse the target page using `agent-web-interface-guide` to discover the actual selectors before writing code — do not guess
-- Spot-check 2-3 critical selectors with `find` or `get_element` to confirm they resolve to the intended elements
-
-### 4. Implement Tests
-- Add/adjust fixtures and page objects first (if needed)
-- Write tests in a story-like flow with AAA structure: Arrange → Act → Assert
-- Add assertions that represent user outcomes
-- **For large suites:** Use subagents (Task tool) to write individual test files in parallel.
-  Pass each subagent the test case spec path, codebase conventions from Step 2, and the
-  operating principles from this skill. Only split when files have independent responsibilities.
-
-### 5. Stabilize
-- Replace any sleeps with meaningful waits
-- Tighten locators to avoid ambiguity
-- For network-driven flows, use `page.waitForResponse` for critical checkpoints
-
-### 6. Verify
-- Run the smallest relevant test command: `npx playwright test <file> --reporter=list 2>&1`
-- In CI or headless environments (no display), never use `--headed` — it will fail silently or hang
-- Use `--headed` only during local interactive debugging when you need to visually observe the test
-- Fix root causes rather than extending timeouts
-
-### 7. Summarize
-Return:
-1. **What I changed** (bullets)
-2. **Test case IDs added** (list all new TC-IDs with brief description)
-3. **Why it's stable** (locator/wait strategy used)
-4. **How to run** (exact commands)
-5. **Notes / follow-ups** (optional)
-
-## Operating Principles (Non-Negotiable)
-
-### Test User Outcomes
-Assert what the user sees — visible text, URL changes, enabled/disabled states — not internal state, CSS classes, or component hierarchy.
-
-### No Arbitrary Sleeps
-Avoid `page.waitForTimeout()` except as a last-resort debug aid — remove before finishing.
-
-### Locator Strategy
-| Priority | Method | When to Use |
-|----------|--------|-------------|
-| 1 | `getByRole('role', { name })` | Buttons, links, headings, form controls |
-| 2 | `getByLabel()` | Form fields with visible labels |
-| 3 | `getByPlaceholder()` | Inputs with placeholder text |
-| 4 | `getByTestId()` | When data-testid is available |
-| 5 | `getByText()` | Short, stable text (avoid marketing copy) |
-| 6 | CSS selectors | Last resort, always scoped tightly |
-
-Avoid `.first()` / `.nth()` unless a strong, documented reason exists — scope locators to a container instead.
-
-**Within-file consistency:** Every test file must use ONE locator approach for equivalent elements. Do not mix `getByPlaceholder('Email')` in one test with `page.locator('input[placeholder="Email"]')` in another test within the same file. When adding tests to an existing file, match the locator style already in use. If the existing style is suboptimal, refactor all locators in the file together — do not create inconsistency.
-
-### Waiting Strategy
-- Prefer Playwright auto-waits via actions and `expect(...)` assertions
-- If explicit waiting needed, wait for meaningful state: visibility, enabled, URL, specific network response, spinner gone
-
-### Test Case IDs
-- Every test MUST have a unique TC-ID: `TC-<FEATURE>-<NUMBER>`
-- Include in test title: `test('TC-LOGIN-001: User can log in with valid credentials', ...)`
-- Sequential within feature area, never reused
-- When adding to existing file, check existing IDs and continue the sequence
-
-### POM + Fixtures
-- If the project has a `pages/` directory or BasePage class, ALL new tests MUST use Page Objects for interactions
-- Page Objects contain HOW (locators + interactions)
-- Tests contain WHAT (behavior/outcome to verify)
-- Keep page objects thin and composable
-- If the boilerplate shipped a BasePage that no tests reference, either extend it for your feature or flag it for removal — do not leave dead infrastructure
-
-### Determinism and Isolation
-- Tests must not depend on execution order
-- Use unique test data per test or suite
-- **Parallel-safe mutations:** When `fullyParallel: true` is configured, tests run concurrently across workers. A test that creates a record (e.g., a ticket) and then asserts it appears in a list WILL race with other tests creating records. Solutions: (a) assert on the specific record you created (filter/search by the unique ID from your API setup), not on list position or count; (b) use `test.describe.serial` for flows that genuinely require sequence (create-then-verify); (c) scope list assertions with `.filter({ hasText: uniqueIdentifier })` to avoid seeing other workers' data.
-
-### Assertions
-- Use Playwright `expect` matchers (auto-retry, better error messages)
-- Avoid `isVisible()` + `expect(true)` pattern
-
-### Configuration Hygiene
-- Use `baseURL` and relative navigation (`page.goto('/')`)
-- Avoid hardcoded domains/URLs in tests
-- Configure `trace: 'on-first-retry'`, `screenshot: 'only-on-failure'`, `video: 'on-first-retry'` for CI debugging
-- Set `retries: process.env.CI ? 2 : 0` — retries in CI only
-- View traces with `npx playwright show-trace trace.zip` to time-travel through failures
-- If `tsconfig.json` defines path aliases (e.g., `@pages/*`, `@fixtures/*`, `@utils/*`), use them in imports instead of relative paths. Check tsconfig paths before writing any import statement.
-
-### Authentication Setup
-Use `storageState` for most projects (log in once in global setup, reuse across tests).
-For parallel workers needing separate accounts, use worker-scoped fixtures.
-For multi-role tests (admin + user), create separate browser contexts.
-Per-test login is only for testing the login flow itself.
-Never hardcode tokens — use environment variables or `.env.test`.
-
-See [references/auth-patterns.md](references/auth-patterns.md) for full patterns with code examples.
-
-### API-Driven Test Setup and Teardown
-Use API calls (not UI clicks) to seed test data — 10-50x faster and more reliable.
-Use UI setup only when the creation flow IS the test. Tests that create persistent data
-MUST clean up: use `afterEach` API deletion, fixture-with-cleanup, or bulk `globalTeardown`.
-If no cleanup endpoint exists, document the gap with a TODO.
-
-See [references/api-setup-teardown.md](references/api-setup-teardown.md) for full patterns with code examples.
-
-### Network Interception and Error Paths
-Use `page.route()` to mock server errors, patch responses, assert backend calls, or block
-heavy resources. Every feature needs error path tests: server error (500), network timeout,
-and empty state at minimum.
-
-See [references/network-interception.md](references/network-interception.md) for full patterns with code examples.
-
-### Custom Fixtures (test.extend)
-
-Use `test.extend` to create reusable test setup without duplicating code:
-
-```typescript
-// fixtures/index.ts
-import { test as base, Page } from '@playwright/test';
-import { LoginPage } from '../pages/LoginPage';
-
-export const test = base.extend<{
-  loginPage: LoginPage;
-  authenticatedPage: Page;
-}>({
-  loginPage: async ({ page }, use) => {
-    await use(new LoginPage(page));
-  },
-  authenticatedPage: async ({ browser }, use) => {
-    const context = await browser.newContext({
-      storageState: 'tests/.auth/user.json'
-    });
-    const page = await context.newPage();
-    await use(page);
-    await context.close();
-  },
-});
-export { expect } from '@playwright/test';
-```
-
-Import `test` from your fixtures file, not from `@playwright/test`, in test files that need custom fixtures.
-
-### Mapping Tables
-When converting journey specs or exploration results to code, consult the mapping tables
-for standard translations of scopes, actions, assertions, and target kinds to Playwright API calls.
-For low-confidence journey steps (<0.7), add extra assertions and include fallback locators as comments.
-
-See [references/mapping-tables.md](references/mapping-tables.md) for the full tables.
-
-## Test Template
-
-```typescript
-// If the project has custom fixtures (fixtures/index.ts), import from there:
-//   import { test, expect } from '@fixtures/index';
-// Otherwise, use the default:
-import { test, expect } from '@playwright/test';
-
-test('TC-FEATURE-001: Description of test case', async ({ page }) => {
-  // Arrange
-  await page.goto('/feature-path');
-
-  // Act
-  await page.getByRole('button', { name: /submit/i }).click();
-
-  // Assert
-  await expect(page.getByText(/success/i)).toBeVisible();
-});
-```
-
-Always check for a project fixtures file before using the default import. If custom fixtures exist, you MUST import from them to get access to page objects and custom setup.
-
-## Anti-Patterns (Quick Reference)
-1. Raw CSS selectors — use semantic locators
-2. `waitForTimeout()` — use proper assertions/waits
-3. Fragile `.nth()` / `.first()` — scope to container
-4. Exact long text matches — use regex with key words
-5. Unscoped locators — scope to container
-6. Login via UI in every test — use storageState
-7. UI clicks for test data setup — use API
-8. No error path tests — add failure scenarios
-9. Hardcoded test data — use API setup + dynamic values
-10. Tests depending on execution order
-11. `expect(await el.isVisible()).toBe(true)` — use `await expect(el).toBeVisible()`
-12. `{ force: true }` — diagnose root cause instead
-13. `networkidle` as default wait — use specific response waits
-14. CSS utility class selectors (Tailwind/Bootstrap)
-15. Asserting exact server-computed values — use patterns or seed data
-
-See [references/anti-patterns.md](references/anti-patterns.md) for detailed explanations and fix strategies.

package/dist/2.0.9/codex/plugin/skills/write-test-code/agents/claude.yaml

@@ -1,3 +0,0 @@
-frontmatter:
-  argument-hint: "<test description or path to test case spec file>"
-  user-invocable: true

package/dist/2.0.9/codex/plugin/skills/write-test-code/agents/openai.yaml

@@ -1,10 +0,0 @@
-interface:
-  display_name: "Implement Playwright Tests"
-  short_description: "Implement or refactor executable Playwright tests from a scenario or spec"
-  default_prompt: "Write or update Playwright E2E tests for this scenario or TC-ID spec."
-
-dependencies:
-  tools:
-    - type: "mcp"
-      value: "agent-web-interface"
-      description: "Browser automation MCP used when selectors or live behavior need verification"

package/dist/2.0.9/codex/plugin/skills/write-test-code/references/anti-patterns.md

@@ -1,88 +0,0 @@
-# Anti-Patterns: Detailed Explanations and Fix Strategies
-
-## 1. Raw CSS selectors
-Use semantic locators (`getByRole`, `getByLabel`, `getByTestId`) instead of CSS selectors. CSS selectors are brittle and break when markup changes.
-
-**Why:** A class rename, component refactor, or CSS-in-JS migration breaks every CSS-based selector overnight. Semantic locators survive these changes because they target accessible roles and labels, not implementation details.
-
-**Fix:** Replace `page.locator('.submit-btn')` with `page.getByRole('button', { name: /submit/i })`. Follow the locator strategy hierarchy in the main skill.
-
-## 2. `waitForTimeout()`
-Use proper assertions and event-driven waits. `waitForTimeout()` adds arbitrary delays that slow tests and mask timing issues.
-
-**Why:** A 2-second sleep that works locally may be too short in CI (slower machines) or too long everywhere (wasting time). It also hides the real question: "what am I actually waiting for?"
-
-**Fix:** Replace with `waitForResponse` for API-dependent UI, `expect(el).toBeVisible()` for element appearance, or `expect(spinner).toBeHidden()` for loading states.
-
-## 3. Fragile `.nth()` / `.first()`
-Scope locators to a container instead of relying on position. If unavoidable, add a comment explaining why.
-
-**Why:** Element order can change when the page adds a banner, reorders a list, or renders asynchronously. `.first()` silently picks the wrong element, causing false passes or mysterious failures.
-
-**Fix:** Use `.filter({ hasText: 'Specific Item' })` or scope to a container: `page.locator('[data-testid="cart"]').getByRole('button')`.
-
-## 4. Exact long text matches
-Use regex with key words instead of matching entire strings. Marketing copy and UI text change frequently.
-
-**Why:** A copywriter changes "Sign up for free today!" to "Create your free account" and every test matching the full string breaks, even though the feature works fine.
-
-**Fix:** Use `page.getByText(/sign up/i)` or `page.getByRole('button', { name: /free/i })` — match the stable semantic keywords.
-
-## 5. Unscoped locators
-Scope locators to `main`, `nav`, `dialog`, or other containers when possible. Global locators match unintended elements.
-
-**Why:** A page-wide `getByRole('button', { name: /submit/i })` may match a submit button in the header, footer, or a hidden modal — not just the one in your form. This causes the wrong click or ambiguous locator errors.
-
-**Fix:** Scope first: `page.locator('main').getByRole('button', { name: /submit/i })` or `page.locator('[role="dialog"]').getByRole('button')`.
-
-## 6. Login via UI in every test
-Use `storageState` or API-based auth setup. UI login in every test wastes time and creates coupling to the login flow.
-
-**Why:** If every test clicks through the login form, a single login page change breaks the entire suite. It also adds 3-10 seconds per test — multiplied across hundreds of tests, this becomes significant CI time.
-
-**Fix:** Log in once in `globalSetup`, save `storageState` to a JSON file, and reuse it. See `references/auth-patterns.md` for the four auth strategies.
-
-## 7. UI clicks to set up test data
-Use API requests for data seeding. UI setup is 10-50x slower and more fragile than API calls.
-
-**Why:** Creating a product via the admin UI takes 15+ seconds and 10+ actions. An API call takes 200ms and one line. UI setup also couples your test to two features instead of one — if the admin form breaks, your unrelated cart test fails too.
-
-**Fix:** Use the `request` fixture: `await request.post('/api/products', { data: { ... } })`. See `references/api-setup-teardown.md`.
-
-## 8. No error path tests
-Every feature needs at least one failure scenario test. Cover server errors (500), network timeouts, and empty states.
-
-**Why:** Happy-path-only suites give false confidence. The app may crash on a 500, show a blank screen on empty data, or hang on a timeout — none of which are caught without explicit error path tests.
-
-**Fix:** Use `page.route()` to mock failures. At minimum: one 500 response, one timeout (`route.abort('timedout')`), one empty state (`route.fulfill({ json: { items: [] } })`). See `references/network-interception.md`.
-
-## 9. Hardcoded test data
-NEVER embed real entity IDs (`'ACC-SUB-2026-00025'`), real user names (`'Anas Client 73'`), real monetary amounts, or environment-specific strings in test code. Instead:
-- Create data via API in `beforeEach` and capture the returned ID
-- Use `Date.now()` or `crypto.randomUUID()` suffixes for uniqueness
-- Read values from `process.env` or a test data module
-- For read-only assertions on existing data, use pattern matchers (`expect(text).toMatch(/ACC-SUB-\d{4}-\d{5}/)`) instead of exact values
-
-If you find yourself typing a specific ID or name into test code, STOP — that is a hardcoded value.
-
-## 10. Tests depending on execution order
-Each test must be independently runnable. Never rely on state left by a previous test.
-
-## 11. `expect(await el.isVisible()).toBe(true)`
-Use `await expect(el).toBeVisible()` instead. The Playwright assertion auto-retries, while the manual pattern checks once and fails on timing.
-
-## 12. `{ force: true }` on clicks/checks
-Hides real interaction problems (overlapping elements, not scrolled into view, disabled state). Diagnose the root cause instead: use `scrollIntoViewIfNeeded()`, wait for overlay to disappear, or wait for element to be enabled. Only acceptable when interacting with a custom widget that Playwright cannot natively trigger (document why in a comment).
-
-## 13. `waitForLoadState('networkidle')` as default strategy
-`networkidle` waits for 500ms of no network activity, which breaks on long-polling, WebSockets, analytics beacons, or chat widgets. Use it ONLY for initial full-page loads where no streaming/polling exists. For post-action waits, use `waitForResponse` targeting the specific API call, or assert directly on the resulting UI state (Playwright auto-retries).
-
-## 14. CSS utility class selectors (Tailwind, Bootstrap, etc.)
-`button.rounded-l-lg`, `.flex.items-center`, `.bg-primary` are styling concerns that change during refactors. Treat ALL utility framework classes as volatile — never use them as selectors. If no semantic locator works, request a `data-testid` from the dev team.
-
-## 15. Asserting exact server-computed values
-`expect(revenue).toHaveText('12450')` will break when data changes. For dashboard counters, totals, and aggregates:
-- Assert the element exists and contains a number (`toMatch(/\$[\d,]+/)`)
-- Assert non-zero or within a range
-- Assert format correctness (`/^\d{1,3}(,\d{3})*$/`)
-- If exact value matters, seed the data via API first so you control the expected value

package/dist/2.0.9/codex/plugin/skills/write-test-code/references/api-setup-teardown.md

@@ -1,83 +0,0 @@
-# API-Driven Test Setup and Teardown
-
-## API-Driven Test Setup
-
-Use API calls to set up test data instead of clicking through UI. This is 10-50x faster and more reliable.
-
-**When to use API setup:** Creating test users, products, orders, seed data. Setting feature flags. Resetting state between tests.
-
-**When to use UI setup:** Only when the creation flow IS the test being verified.
-
-```typescript
-test('TC-CART-001: User sees items in cart', async ({ page, request }) => {
-  // Arrange: seed data via API (fast, deterministic)
-  await request.post('/api/cart/items', {
-    data: { productId: 'SKU-123', quantity: 2 }
-  });
-
-  // Act: navigate to verify UI
-  await page.goto('/cart');
-
-  // Assert
-  await expect(page.getByRole('listitem')).toHaveCount(2);
-});
-```
-
-**Reusable API fixture pattern:**
-```typescript
-export const test = base.extend<{ apiClient: APIRequestContext }>({
-  apiClient: async ({ playwright }, use) => {
-    const ctx = await playwright.request.newContext({
-      baseURL: process.env.API_BASE_URL,
-      extraHTTPHeaders: { Authorization: `Bearer ${process.env.API_TOKEN}` },
-    });
-    await use(ctx);
-    await ctx.dispose();
-  },
-});
-```
-
-## Test Data Teardown
-
-Tests that create persistent data (database records, uploaded files, user accounts) MUST clean up after themselves. Leaked test data accumulates across runs and causes false positives/negatives in other tests (pagination counts drift, filter results change, list assertions break).
-
-### Strategy 1: API teardown in afterEach (Recommended)
-
-```typescript
-let createdTicketId: string;
-
-test.beforeEach(async ({ request }) => {
-  const resp = await request.post('/api/tickets', {
-    data: { title: `Test ${Date.now()}` }
-  });
-  createdTicketId = (await resp.json()).id;
-});
-
-test.afterEach(async ({ request }) => {
-  if (createdTicketId) {
-    await request.delete(`/api/tickets/${createdTicketId}`);
-  }
-});
-```
-
-### Strategy 2: Fixture with automatic cleanup
-
-```typescript
-export const test = base.extend<{ testTicket: { id: string; title: string } }>({
-  testTicket: async ({ request }, use) => {
-    const resp = await request.post('/api/tickets', {
-      data: { title: `Test ${Date.now()}` }
-    });
-    const ticket = await resp.json();
-    await use(ticket);
-    // cleanup runs automatically when test finishes
-    await request.delete(`/api/tickets/${ticket.id}`);
-  },
-});
-```
-
-### Strategy 3: Bulk cleanup in globalTeardown
-
-For environments where individual deletion is impractical, tag test data (e.g., `title LIKE 'Test %'`) and delete in batch during `globalTeardown.ts`.
-
-If the cleanup API endpoint is unknown, do not invent one. Leave a clear `TODO` with the missing endpoint details, document the cleanup gap in the test file or tracker, and prefer fixture-scoped or environment reset strategies that you can verify. If cleanup is genuinely impossible (no API, no database access), document this as a known limitation in the test file header AND add an `afterEach` that logs a warning.