ADR-002: Web testing stack — Vitest + Playwright opt-in
Status: Accepted Date: 2026-05-22
Context
Section titled “Context”The web-nextjs shape needs a testing stack. Options considered: Vitest only, Vitest + Playwright opt-in, Jest + Playwright.
Decision
Section titled “Decision”Vitest is on by default for unit and component tests. The web-nextjs Copier template includes a needs_e2e? prompt — when true, an e2e/ directory with a Playwright scaffold is generated plus a devbox run e2e recipe.
Rationale
Section titled “Rationale”- Vitest is the modern default for TS/ESM projects: faster than Jest, native TS, native ESM, Vite-aligned.
- Playwright is the right e2e tool but adds CI weight (browser downloads, flakiness budget). Making it opt-in keeps simple repos lean.
- A single Copier prompt is a cheaper UX than asking every team to bolt Playwright on later.
Consequences
Section titled “Consequences”- The web
testeragent handles bothvitestand (when present)playwright— must inspect the repo to know which to run. - CI workflow template has two jobs:
test(always) ande2e(conditional one2e/existing). - Trade-off: a repo that initially opted out can
copier update --data needs_e2e=trueto add Playwright later.