@athenaflow/plugin-e2e-test-builder 2.0.9

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

@@ -0,0 +1,147 @@
+---
+name: review-test-cases
+description: >
+  This skill should be used when a quality review of TC-ID test case specifications is needed before writing executable
+  test code. It reviews the spec artifact only; it does not implement or rewrite tests.
+  Triggers: "review test cases", "check test specs", "review TC-IDs", "audit test coverage",
+  "are my test cases good", "validate test specs", "review test-cases/*.md",
+  "check for gaps in test cases", "review before writing tests", "quality check test specs".
+  Inserted as a quality gate between generate-test-cases and write-test-code — catches
+  gaps, duplication, weak assertions, missing error paths, and invented scenarios before they get
+  encoded into test code. Review-only — does NOT modify the spec file, does NOT write test code.
+  The write-test-code skill should be used for implementation.
+allowed-tools: Read Glob Grep Task
+---
+
+# Review Test Cases
+
+Review TC-ID test case specifications for completeness, accuracy, and quality before they are implemented as executable Playwright tests. This is a quality gate — catch problems in the spec, not in the code.
+
+## Input
+
+Parse the spec file path from: $ARGUMENTS
+
+If no argument provided, search for `test-cases/*.md` files and review the most recently modified one.
+
+## Workflow
+
+### Step 1: Load the Spec and Context
+
+1. Read the test case spec file
+2. Read any related files for context:
+   - `e2e-plan/conventions.md` or `e2e-plan/coverage-plan.md` if they exist
+   - `e2e-tracker.md` if it exists (to understand what was explored)
+3. Extract the target URL from the spec header
+
+### Step 2: Run the Review Checklist
+
+Evaluate every test case against each criterion. Track findings by severity:
+
+- **BLOCKER** — must fix before writing tests (missing critical paths, invented behavior, wrong URL)
+- **WARNING** — should fix, will cause problems in implementation (vague steps, weak assertions, duplication)
+- **SUGGESTION** — optional improvement (priority adjustment, better categorization, additional edge case)
+
+#### 2a. Coverage Completeness
+
+| Check | What to Look For |
+|-------|-----------------|
+| Happy path present | At least one Critical-priority test covers the primary success flow end-to-end |
+| Error paths covered (MINIMUM) | Every spec MUST have at least: (1) one server error test (500), (2) one network failure test (timeout/offline), (3) one empty state test. If auth is involved: (4) one session expiry test. Missing any of these is a BLOCKER, not a suggestion |
+| Boundary conditions | Min/max values, empty inputs, special characters, long strings |
+| Authentication edge cases | Session expiry, unauthorized access, role-based differences (if applicable) |
+| Navigation edge cases | Back/forward, direct URL access, refresh mid-flow |
+| Missing user actions | Every interactive element on the page should appear in at least one test case |
+
+#### 2b. Specification Quality
+
+| Check | What to Look For |
+|-------|-----------------|
+| Steps are concrete | "Click the Submit button" not "submit the form"; "Enter 'test@example.com' in Email field" not "enter email" |
+| Expected results are observable | Specific text, URL change, element state — not "page updates" or "works correctly" |
+| Preconditions are explicit | Auth state, test data, feature flags, starting URL — nothing assumed |
+| TC-IDs are sequential | No gaps, no duplicates, correct feature prefix |
+| Priority is justified | Critical = blocks core journey; not everything is Critical |
+| Categories are accurate | Happy Path vs Validation vs Edge Case — correctly classified |
+
+#### 2c. Invented vs Observed
+
+This is the most important check. Test cases should trace back to behavior that was actually observed or deliberately triggered during exploration, not assumed.
+
+Red flags for invented scenarios:
+- Specific error message text that wasn't observed (e.g., "Please enter a valid email" when the actual message might differ)
+- Assumptions about validation rules without exploration evidence (e.g., "minimum 8 characters" without trying it)
+- Test cases for UI elements that may not exist (e.g., "retry button" on error page without visiting the error page)
+- Server-side behavior assumptions (e.g., "rate limit after 5 attempts" without evidence)
+
+When suspicious: delegate a spot-check to a subagent with browser access (Task tool). Pass it the target URL, the specific TC-IDs under suspicion, and the claims to verify (element existence, error message text, validation behavior). The subagent should return structured evidence: what it found, what matched, what differed.
+
+#### 2d. Duplication and Overlap
+
+- Flag test cases that test the same behavior with trivially different inputs
+- Flag test cases where the steps are identical but expected results differ only cosmetically
+- Merging candidates: cases that could be combined into a single parameterized test without losing coverage
+
+#### 2e. Implementability
+
+- Flag steps that cannot be automated with Playwright (e.g., "verify email arrives", "check database directly")
+- Flag preconditions that require manual setup with no automation path
+- Flag assertions that require visual comparison without specifying tolerance
+- Flag test cases that depend on third-party services (payment processors, OAuth providers) without a mock strategy
+
+### Step 3: Produce the Review Report
+
+Output a structured review with this format:
+
+```markdown
+# Test Case Review: <feature>
+
+**Spec file:** <path>
+**Total test cases:** <count>
+**Review date:** <date>
+
+## Verdict: PASS | PASS WITH WARNINGS | NEEDS REVISION
+
+## Blockers (<count>)
+- **TC-<ID>**: <issue description>
+
+## Warnings (<count>)
+- **TC-<ID>**: <issue description>
+
+## Suggestions (<count>)
+- **TC-<ID>**: <issue description>
+
+## Coverage Gaps
+- <Missing scenario that should be added>
+
+## Duplication
+- **TC-<ID>** and **TC-<ID>**: <overlap description>
+
+## Summary
+<2-3 sentences on overall spec quality and what to address before implementation>
+```
+
+### Step 4: Verdict Rules
+
+- **PASS** — no blockers, 2 or fewer warnings. Proceed to write-test-code.
+- **PASS WITH WARNINGS** — no blockers, 3+ warnings. Can proceed but should address warnings.
+- **NEEDS REVISION** — 1+ blockers. Do not proceed to write-test-code until blockers are resolved.
+
+Example: 0 blockers + 2 warnings = PASS. 0 blockers + 3 warnings = PASS WITH WARNINGS. 1+ blockers = NEEDS REVISION regardless of warning count.
+
+## Principles
+
+- **Review-only** — never modify the spec file; report findings for the author to act on
+- **Evidence over opinion** — cite specific TC-IDs and quote specific steps/assertions when flagging issues
+- **Spot-check against live site** — delegate to a subagent with browser access to verify 2-3 suspicious claims rather than trusting all text at face value
+- **Bounded output** — the review report should be actionable and finite, not an exhaustive rewrite
+- **Severity matters** — distinguish blockers from suggestions; not every imperfection is worth fixing before implementation
+
+## Example Usage
+
+```
+Claude Code: /review-test-cases test-cases/login.md
+Codex: $review-test-cases test-cases/login.md
+
+Claude Code: /review-test-cases test-cases/checkout.md
+Codex: $review-test-cases test-cases/checkout.md
+```

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

@@ -0,0 +1,3 @@
+frontmatter:
+  argument-hint: "<path to test-cases/*.md spec file>"
+  user-invocable: true

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

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Review TC-ID Specs"
+  short_description: "Review TC-ID specs for gaps, duplication, and weak assertions"
+  default_prompt: "Review these TC-ID test case specifications before implementation and flag quality issues."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "agent-web-interface"
+      description: "Browser automation MCP used to spot-check observed behavior claims against live site"

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

@@ -0,0 +1,189 @@
+---
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,227 @@
+---
+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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,10 @@
+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"