# Mission: Robust frontend test suites

> Supersedes the former `concurrency/` path (2026-08-24), which had the same mission under a
> narrower name: *"Concurrency (for a robust Playwright suite)."* Its lessons A1–A4, its
> assessment and its suite findings are all still live and carried forward in `STATUS.html`.
> The scope widened on 2026-09-08 to include determinism, test-level allocation and the
> canvas editor, so the directory was renamed to match.

## Why

Flowbase has ~200 Playwright specs against a real backend, and the suite is already
disciplined: test-id-only selectors, Page/Component Objects, methods that own their waits,
auto fixtures that abort on unexpected backend errors, console errors, or a page still
fetching at teardown. Zero `waitForTimeout` in the whole tree. And yet `retries: 3` is
load-bearing, which means the suite is still absorbing flakes rather than not having them.

Martin wants three things that all bottom out in the same skill: **ship on green with no
manual QA**, **write the testing standard the team follows**, and **cut CI wall-clock and
flake rate**. Right now the suite is one level — every test is a Google-sized *large* test
driving a real backend in real time — so reliability and speed are both structurally
capped. Flake rate is measured — in Sentry — but there is no *per-spec* score that says
which tests account for it, and `page.clock` and `page.route` are used nowhere at all: time
and network are left to chance on purpose-by-default rather than by decision.

## Success looks like

- Can name a flake's root cause from the canonical taxonomy (async-wait, order dependency,
  concurrency, resource leak, time, randomness, network, hardware) after reading a trace,
  and say which of the eight it is before proposing a fix.
- Has a **per-spec flakiness score** (entropy + flip rate, per Kowalczyk et al.) on top of
  the suite-level rate already visible in Sentry, and can name the three specs that account
  for most of it.
- Can defend `retries: N` as a deliberate policy with a stated cost, or replace it with a
  quarantine + budget policy, and explain to the team why re-running is not a fix.
- Can decide, for any new behaviour, which level tests it — browser E2E against the real
  backend, browser test against an intercepted network, component test, or pure unit — and
  justify it in terms of what failures each level can and cannot see.
- Can make a test deterministic in the three dimensions the suite currently leaves to
  chance: **time** (no `page.clock` anywhere today), **network** (essentially no
  `page.route`), and **shared backend state** (parallel workers on one database).
- Can test the canvas editor's *behaviour* — transform maths, snapping, selection,
  keyframes — without pixel snapshots, and knows exactly which editor properties are only
  reachable by pixels.
- Can prove a test has power: mutate the source, watch the test fail, keep the test.
- Can write the team's testing conventions as reviewable rules with a stated reason each —
  the `e2e/CLAUDE.md` upgrade path.

Carried forward from the `concurrency/` mission and still open:

- Can reason about worker-level parallelism: what is shared, what is isolated, and exactly
  where two workers can collide — across all seven layers, not just the database.
- Can state the trade-offs of a chosen isolation design out loud: throughput vs. isolation
  vs. debuggability, with a price on each.
- Knows when a retry is a legitimate instrument (counted, budgeted, ratcheted) and when it
  is hiding a bug.

## Constraints

- Real production suite, real team. Every lesson must cash out as a rule in
  `e2e/CLAUDE.md`, a config change, or a diff in `apps/frontend/e2e`. No toy apps.
- Strong practitioner with a working, sophisticated suite. Expect fast uptake on
  mechanism; the gaps are in **measurement**, **level allocation**, and the
  **literature's vocabulary** for what he's already doing by instinct.
- Existing hard conventions (`e2e/CLAUDE.md`): test-ids only, black-box (no `src/`
  imports), generated types mandatory, methods own their waits, gestures via `lib/editor`,
  inline styles not computed. Lessons must respect these or argue explicitly against one.
- Three surfaces in scope, all of them: the Figma-like editor (Gesto/Selecto/Moveable on
  canvas), the manually-handled TanStack Query layer, and ordinary SaaS forms and tables.
- Code examples in TypeScript.
- **One question at a time.** No compound questions — never bundle two asks behind one
  question mark, in calibration or in exercises. Each question probes exactly one thing.

## Out of scope

- Cross-browser and cross-device. The suite is Desktop Chrome only, on purpose.
- Visual regression / pixel snapshotting as a *practice*. It stays in scope only as the
  thing we deliberately decline, and we need to know precisely what we give up.
- Backend testing. The API is a dependency to be controlled, not a subject.
- Accessibility auditing as a goal in itself (ARIA-role locators are banned here, which is
  a live tension worth one lesson — but a11y testing is not the mission).
- Load and performance testing.