# E2E Test Implementation

## Browser Harness Resolution

Inspect the repository's browser-test configuration, scripts, fixtures, neighboring tests, and CI routing. Preserve the existing harness, imports, locator conventions, setup lifecycle, file naming, and test location.

When no browser harness exists, use integration-e2e-testing to determine whether browser-level proof is necessary. If it is, select the lowest-surface sufficient harness from repository and applicable external evidence; if it is not, use the cheaper observable boundary. Report an unavailable execution environment as a proof limitation rather than a user decision.

## Lane Selection

- `fixture-e2e`: run a real browser against deterministic fixture or intercepted backend behavior.
- `service-integration-e2e`: run against the required local services or stubs when correctness depends on persistence, transactions, or cross-service contracts.

Preserve the lane selected by the skeleton. A lane change requires evidence that the original lane cannot prove the accepted behavior.

## Structure and Reuse

- Follow the repository's existing browser abstraction and paths.
- When establishing an approved new Playwright convention, use `*.fixture.e2e.test.ts` and `*.service.e2e.test.ts`, or the naming defined by the parent test skill.
- Introduce a page object when one interaction is reused across 3+ tests or a coherent workflow would otherwise be duplicated. Keep direct accessible locators for a small, local test.

## Fixture Lane

Use the repository's existing route interception or fixture-loader boundary. Fixtures are deterministic, local to the test or suite, and shaped like the real contract. The browser still exercises the actual UI, navigation, and state updates.

## Service Lane Prerequisites

Before implementation or execution, identify:

- service start and health-check commands;
- test-safe database or data target;
- deterministic seed and cleanup mechanism;
- authentication setup;
- required environment variables and external stubs.

Use the repository's existing seed and authentication mechanisms. Create per-test data with unique identifiers and clean it through the supported API, database fixture, or teardown path. When a required prerequisite is unavailable and adding it is outside approved scope, return the missing prerequisite instead of substituting fixture behavior.

## Locator and Assertion Rules

- Follow the repository's locator convention; otherwise prefer accessible role/name or label locators, then stable test IDs when no semantic locator exists.
- Assert user-observable state, navigation, accessibility, or persisted behavior named by the skeleton. Treat assertions tied only to CSS classes or internal DOM structure as insufficient proof.
- When the UI specification defines responsive behavior, run the affected interaction at the specified viewport; otherwise use the repository's default browser matrix.
- Each test starts from isolated state and remains independent of execution order.

## Skeleton Comment Format

Preserve the skeleton's annotations using the source language's comment syntax:

```text
AC: [acceptance criterion]
Behavior: [trigger] → [process] → [observable result]
@category: fixture-e2e | service-integration-e2e
@lane: fixture-e2e | service-integration-e2e
@dependency: none | [dependency names] | full-system
@complexity: low | medium | high
ROI: [score]
```

When `Verification items:` are present, implement and assert every listed item.

# Frontend Test Implementation (React/TypeScript)

## Project Toolchain Resolution

Before writing a test, inspect package scripts, runner configuration, setup files, neighboring tests, DOM/browser environment, and network handlers. Preserve the repository's runner, imports, mock API, setup lifecycle, file naming, and test location.

- Use React Testing Library when it is the project's component-test renderer; prefer `userEvent` for user interactions.
- Use the repository's network mocking layer for API behavior. When MSW is configured, extend its handlers instead of adding runner-level fetch mocks.
- Use the configured runner's imports, module-mocking API, fake timers, and reset conventions.
- When multiple approaches coexist, follow the dominant convention in the changed feature area. If none is representative and adding or replacing tooling is outside the approved work, report the missing test-environment decision.

## Test Scope

- Concentrate rigor on shared components, hooks, and utilities with a wide blast radius. Use integration or E2E coverage for higher-composition surfaces when their boundary is the behavior under test.
- For a behavior-preserving refactor, establish passing regression or characterization evidence before the change and rerun it afterward.
- Test-first scope covers executable behavior; configuration that changes runtime or build behavior requires executable validation.
- Continuity tests cover existing feature behavior affected by the change; long-term performance and operational testing remain infrastructure concerns unless the accepted work includes them.

## Mock Boundary

- For network behavior, use the repository's network-level mock layer rather than mocking implementation modules.
- Mock only direct external I/O. Exercise internal utilities, business logic, and the component boundary under test through real implementations.
- Keep test data minimal and free of real sensitive values.

## Failure Classification

| Evidence | Action |
|---|---|
| Expected value or test setup contradicts the accepted contract | Fix the test |
| Implementation violates the accepted behavior or boundary | Fix the implementation |
| Both interpretations remain compatible with available requirements | Return the unresolved behavior decision |

## Helper Decision

Keep setup local until 3+ uses or a named readability/contract benefit justifies a helper. Preserve separate helpers when the scenarios have different ownership or are likely to evolve independently.

## Repository Conventions

- Preserve the repository's test location and naming. For an approved new co-located React convention, use `{ComponentName}.test.tsx`; for integration tests, use `{FeatureName}.integration.test.tsx`.
- Keep tests executable. Fix or remove tests that no longer describe accepted behavior; remove `skip` markers used only to bypass a failure.
- Test rendered output, user interactions, accessibility, and observable error states rather than component internals.

## Assertion Rules

- Use independently derived literal values by default. An approved snapshot, property, or fixture expectation may replace a literal when it provides a clearer independent oracle.
- Every test executes at least one assertion that proves the expected observable behavior.
- Verify final results and state changes; use mock-call assertions only when the call contract itself is the observable boundary.
- For asynchronous UI, use the repository's established async query/wait pattern and assert the resulting user-visible state.