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

package/dist/2.0.8/codex/plugin/skills/generate-test-cases/SKILL.md

@@ -1,184 +0,0 @@
----
-name: generate-test-cases
-description: >
-  Use when the user wants detailed TC-ID test case specifications for a web app feature, not executable code. It explores the target flow, covers happy paths, validation failures, edge cases, and required error states, then writes structured specs under `test-cases/`. Use it after coverage planning or when the user explicitly asks for test cases or TC-IDs. It does not write Playwright code.
-allowed-tools: Read Write Bash Glob Grep Task
----
-
-# Generate Test Cases
-
-Generate comprehensive, structured test case specifications for a web application by exploring it live in a browser.
-
-## Input
-
-Parse the target URL and user journey description from: $ARGUMENTS
-
-## Workflow
-
-### Step 1: Understand the Journey and Existing Coverage
-
-Parse the journey description to identify:
-- **Base URL** and target feature area
-- **Primary user goal** (what the happy path achieves)
-- **Key interaction points** (forms, buttons, navigation, selections)
-- **Implicit requirements** (validation, authentication, authorization)
-
-Check for existing test coverage before exploring:
-- Search for existing test files related to this feature (`Grep` for feature keywords in `**/*.spec.ts`, `**/*.test.ts`)
-- Read any existing `test-cases/*.md` spec files for this feature
-- Note existing TC-IDs to avoid conflicts — continue numbering from the highest existing ID
-- Focus on gaps in existing coverage
-
-### Step 2: Explore the Happy Path
-
-Use a subagent for browser exploration when that saves context. Pass it:
-- The URL and journey description
-- Instructions to walk through each step using `find`, `get_form`, `get_field`
-- Instructions to catalog all interactive elements, form fields, navigation options
-- Instructions to use `get_element` on key elements to capture the best Playwright selector
-- Instructions to return results in this structured format for each step:
-
-```
-Step: <what was done>
-URL: <current URL after action>
-Elements found:
-  - Submit button: getByRole('button', { name: /submit/i })
-  - Email field: getByLabel(/email/i)
-  - Error message: getByText(/required/i)
-Observations: <what appeared, validation messages, state changes>
-```
-
-This structured output ensures selectors survive the handoff to the spec file and ultimately to `write-test-code`.
-
-### Step 3: Explore Alternative and Failure Paths
-
-Launch another subagent, or continue in the main thread if the flow is small, to systematically probe beyond the happy path:
-
-**Validation & Error Handling:**
-- Submit forms with empty required fields
-- Enter invalid formats (wrong email, short passwords, letters in number fields)
-- Exceed field length limits, use special characters and Unicode
-
-**Boundary Conditions:**
-- Min/max values for numeric fields
-- Single character and max length strings
-- Zero quantities, negative numbers, date boundaries
-
-**State & Navigation:**
-- Browser back/forward during multi-step flows
-- Page refresh mid-flow
-- Accessing later steps directly via URL
-
-**UI & Interaction:**
-- Rapid repeated clicks on submit buttons
-- Dropdown default values, empty options
-- Loading states, disabled states, conditional visibility
-
-**Access & Authorization (observe only):**
-- Redirect behavior for unauthenticated users
-- Permission-related error messages
-
-### Step 4: Reason About Additional Scenarios
-
-After exploration, reason about scenarios that could not be directly triggered but must be covered:
-
-- **Network & Performance** — failure modes, slow responses, large data sets, offline behavior
-- **Accessibility (WCAG 2.1 AA)** — keyboard navigation, screen reader support, focus management, contrast
-- **Visual Consistency** — layout stability, responsive breakpoints, dark mode
-- **Cross-browser** — Safari/Firefox/mobile-specific behavioral differences
-- **Concurrent & Session** — session expiry, multi-tab conflicts, race conditions
-
-See [references/scenario-categories.md](references/scenario-categories.md) for detailed checklists within each category.
-
-### Step 5: Generate Test Case Specifications
-
-Write structured test cases to `test-cases/<feature-name>.md`.
-
-## Output Specification
-
-### Test Case Format
-
-```markdown
-### TC-<FEATURE>-<NUMBER>: <Descriptive title>
-
-**Priority:** Critical | High | Medium | Low
-**Category:** Happy Path | Validation | Error Handling | Edge Case | Boundary | Security | Accessibility | Visual | Performance | Network Error | UX
-**Preconditions:**
-- <What must be true before this test>
-
-**Steps:**
-1. <Action the tester performs>
-2. <Next action>
-
-**Expected Result:**
-- <What should happen>
-
-**Selectors observed:**
-- <element>: `getByRole('button', { name: /submit/i })` or `getByLabel(/email/i)` — from `get_element`/`find` during exploration
-- (Include selectors for key interactive elements so `write-test-code` doesn't have to rediscover them)
-
-**Notes:**
-- <Additional context discovered during exploration>
-```
-
-### Output Organization
-
-```markdown
-# Test Cases: <Feature Name>
-
-**URL:** <base URL>
-**Generated:** <date>
-**Journey:** <brief description>
-
-## Summary
-- Total test cases: <count>
-- Critical: <count> | High: <count> | Medium: <count> | Low: <count>
-
-## Happy Path
-## Validation & Error Handling
-## Edge Cases
-## Boundary Conditions
-## Security & Access
-## Network Error Scenarios
-## Visual & Responsive
-## Performance & Loading
-## Accessibility & UX
-```
-
-### File Naming Convention
-
-When generating specs that span multiple roles or test categories, recommend role-based file naming (`*.admin.spec.ts`, `*.user.spec.ts`) or Playwright tag annotations (`@admin`, `@smoke`) in the spec. This enables selective execution via `--grep @admin` or glob patterns instead of fragile `testIgnore` regex in playwright.config.ts. NEVER recommend a `testIgnore` regex that must be updated for every new test file.
-
-### TC-ID Convention
-
-- Format: `TC-<FEATURE>-<NNN>` where NNN is zero-padded to 3 digits
-- Feature abbreviation: short and clear (LOGIN, CHECKOUT, SEARCH, SIGNUP)
-- Start at 001, sequential, unique within the document
-- Happy path first, then validation, then edge cases
-
-## Quality Standards
-
-- Every test case must be **independently executable** — no hidden dependencies
-- Steps must be **concrete and unambiguous** — "click the Submit button" not "submit the form"
-- Expected results must be **observable and verifiable** — include actual error messages observed
-- Priority must be **justified** — Critical = blocks core journey, High = significant, Medium = secondary, Low = cosmetic
-- Every feature spec MUST include at minimum: one network error scenario (500/timeout), one empty state scenario, and one session/auth edge case (if the feature requires auth). These are non-negotiable — omitting them is a BLOCKER in the review-test-cases quality gate.
-- **Test case count guidance:** Aim for 15-30 test cases per feature area as a baseline. Fewer than 10 suggests missing error paths or edge cases. More than 40 suggests the feature should be split into sub-features with separate spec files. Prioritize breadth of category coverage over depth within a single category.
-
-## Blocking Conditions
-
-Report and work around:
-- **Login/auth walls**: Document as precondition, test observable behavior
-- **CAPTCHA**: Report, skip, note in preconditions
-- **Payment gateways**: Don't enter real data, document flow up to that point
-- **Rate limiting**: Slow down, note rate limit behavior as a test case
-
-## Example Usage
-
-```
-Claude Code: /generate-test-cases https://example.com/login User logs in with email and password, sees dashboard
-Codex: $generate-test-cases https://example.com/login User logs in with email and password, sees dashboard
-
-Claude Code: /generate-test-cases https://shop.example.com User searches for product, adds to cart, proceeds to checkout
-Codex: $generate-test-cases https://shop.example.com User searches for product, adds to cart, proceeds to checkout
-```

package/dist/2.0.8/codex/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/skills/review-test-cases/SKILL.md

@@ -1,147 +0,0 @@
----
-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.8/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.