# UI Matrix Coverage Design

**Date:** 2026-07-13
**Slug:** `ui-matrix-coverage`

## Scope

PR CI must detect regressions across every canonical app route, tenant role, module gate, plan tier, critical component state, theme, locale direction, viewport class, and supported browser without a Cartesian-product suite.

Nightly full role × route × theme × locale × viewport coverage is deferred and recorded in `GOLIVE.md`.

## Contracts

- Navigation expectations use an explicit test oracle independent from rendered navigation. Oracle parity fails when canonical routes change without matrix updates.
- PR navigation cases cover OWNER, ADMIN, MEMBER, VIEWER, CONTRACTOR, ACCOUNTANT; every toggleable module disabled once; FREELANCER, BUSINESS, WHITE_LABEL, ENTERPRISE tiers.
- Canonical route smoke checks cover every route with route-specific readiness; no `networkidle` dependency.
- Critical list coverage includes empty, populated, loading, and error states.
- Every implemented canonical route has deterministic behavior coverage for safe controls: navigation, view modes, filters, downloads, retry, and modal open/cancel. Destructive or financial mutations are exercised through disabled-state or confirmation/cancel contracts without committing the mutation.
- Compatibility uses pairwise Chromium/WebKit, desktop/mobile, English/LTR and Hebrew/RTL, light/dark cases.
- Preview-only fixture API creates isolated tenants and role users. It returns 404 outside preview, authenticates with a constant-time secret check, accepts no arbitrary roles, and supports exact cleanup.
- Playwright authenticates through real login and validates `/api/auth/me`; fixture secret never enters browser state or artifacts.
- Component contracts require native `required` propagation, unique Settings action names, complete DataTable ARIA structure, and unconditional dialog focus assertions.
- UI-role tests validate navigation visibility plus targeted direct-route denial for restricted roles and disabled modules; API authorization remains covered by route tests.

## CI

- PR workflow passes `PLAYWRIGHT_BASE_URL`, fixture secret, and deployed preview URL explicitly.
- PR suite uses two workers and targeted WebKit only.
- Screenshots and exhaustive permutations remain nightly-only.
- GitHub `preview` environment must provide isolated Cloudflare account/namespace IDs and pairwise-distinct secrets, with required reviewers enabled. Workflow fails closed while these external prerequisites are absent.

## Verification

- UI/API unit tests, lint, and typecheck.
- Playwright collection and scoped PR suite against preview.
- Fixture route security/cleanup tests.
- Local WebKit execution requires Playwright host dependencies; CI installs them with `playwright install --with-deps`.

## Rationale

Layered independent oracles provide broad deterministic coverage within PR runtime limits; exhaustive visual permutation remains deferred until nightly infrastructure exists.