---
name: creating-journey-e2e-tests
description: Use when deriving Playwright tests from a UJ-NNN journey contract or equivalent flow specification.
---

# Create Journey E2E Tests

Audience: AI coding agents first.

Author tests only. Runtime execution, failure classification, fixes, and deployment belong to project `md-e2e`.

**REQUIRED SUB-SKILLS:** Use `md-e2e-discipline`. Use project `md-verify` for live-runtime rules.

## Reject weak input

Return contract to `create-journeys` when trigger, branch IDs, exact visible oracle, exact durable oracle, forbidden effects, or permission boundary is missing. Never derive smoke tests from weak contracts.

## Coverage table first

Before code, build this table in working notes:

| Branch | Risks | Setup | Real trigger | Visible oracle | Durable oracle | Forbidden effects | Execution class |
|---|---|---|---|---|---|---|---|

Execution class: `local`, `live-required`, `api-only`, or `browser-sensitive`.

Every journey branch MUST map to one test or an exact sibling test reference. Duplicate coverage requires justification.

## Derivation ladder

1. **Canonical happy path:** enter through documented UI trigger; assert exact visible values, authoritative persisted state, external/secondary effects, and fresh-read persistence.
2. **Alternate/failure branches:** start at nearest factory-created valid precondition; drive real failing action; assert exact error/recovery plus absence of every forbidden durable effect.
3. **Permissions:** cover anonymous, wrong role, and wrong owner where applicable; assert UI denial, no sensitive data, and exact API response.
4. **Risk cases:** add applicable idempotency, concurrency, retry, stale-state, boundary, commit-point, money, inventory, and cross-actor assertions.

Use one full UI journey. Do not replay expensive onboarding or payment setup in every branch.

## Deterministic setup

- Create users, vendors, deals, purchases, and reviews through factory verbs or real APIs.
- Never mutate business entities with raw SQL.
- DB reads are allowed only as authoritative assertions.
- Create unique mutable state per test.
- Shared setup MUST be immutable.
- Missing required fixture is setup failure, not `test.skip`.

## Assertion bar

Every assertion MUST discriminate a named realistic regression.

```ts
// DO NOT
expect(status).toBeLessThan(500);
expect(snapshot.status).toMatch(/paid|complete|success/i);
if (await button.isVisible()) await button.click();
await expect(page.locator('body')).toBeVisible();

// DO
expect(status).toBe(200);
expect(snapshot.paymentStatus).toBe('paid');
await expect(button).toBeVisible();
await button.click();
```

Assert business values, not containers: exact item, owner, quantity, amount, currency, status, and resulting actor-visible state.

## Runtime failure capture

Use existing harness primitives to fail on unexpected:

- `pageerror`.
- Console errors/warnings.
- Failed journey-owned requests.

Allowlists MUST match exact known noise and include reason. Never swallow errors globally.

## Traceability

Tag each test with journey, branch, risk, and execution class:

```ts
test('decline preserves unpaid state', {
  tag: ['@UJ-012', '@A1', '@forbidden-side-effect', '@live-required'],
}, async ({ page }) => {});
```

Header points to source journey and sibling coverage. Tags are machine authority; prose is explanatory only.

## Execution manifest

Create or update adjacent `<spec>.manifest.json`:

```json
{
  "version": "journey-e2e/v1",
  "journey": "UJ-012",
  "spec": "tests/e2e/journeys/UJ-012.spec.ts",
  "expectedBranches": ["H1", "A1", "P1"],
  "executionClasses": ["local", "live-required"],
  "projects": ["chromium", "mobile-chrome"],
  "fixtures": ["stripe-vendor"],
  "siblingCoverage": {}
}
```

## Authoring completion gate

- [ ] Coverage table covers every branch and applicable risk.
- [ ] One canonical full UI path drives real entry trigger.
- [ ] Factory/API setup only; no raw SQL business mutation.
- [ ] Exact visible, durable, persistence, and secondary-effect oracles.
- [ ] Failures and denials assert forbidden effects.
- [ ] Every assertion names a realistic killed defect.
- [ ] Stable journey/branch/risk/execution tags.
- [ ] Execution manifest matches discovered tests.
- [ ] Typecheck and lint exit 0.
- [ ] Playwright `--list` discovers expected cases.

Do not run behavioral tests under this skill.