agentic-team 0.0.0-stage → 6.2.0

package/template/skills/web-testing/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: web-testing
+description: "Testing strategy for React web apps — Vite SPA and Next.js. Use for any phase that writes or changes tests in a web app, or that adds an e2e flow."
+---
+
+# Skill: Web Testing
+
+## The fact everything else follows from
+
+**jsdom is not a browser.**
+
+It has no layout engine. `getBoundingClientRect` returns zeros, nothing
+scrolls, CSS is parsed but never applied, focus order is approximated, and
+`:hover`, media queries and container queries do not exist. A component can
+be invisible, unclickable, or overlapping another and every jsdom test still
+passes.
+
+So component tests run in **real Chromium** through Vitest browser mode.
+That is already configured by the stack — do not replace it with jsdom
+because a test is awkward. The awkwardness is usually the bug.
+
+## The layers
+
+| Layer | What belongs here | Runs in |
+|---|---|---|
+| Pure logic | Formatting, validation, reducers, date and money math — extracted **out** of components | Node |
+| Component | Render, interact, assert behaviour and accessibility | **Real Chromium** |
+| API seam (MSW) | Our own backend, faked at the network layer | Chromium |
+| E2E (Playwright) | 3–5 journeys against the **built** app | Real browser |
+| Build | `vite build` / `next build` | The gate |
+
+## Query by role, never by test id
+
+```ts
+screen.getByRole("button", { name: "Save changes" });   // yes
+screen.getByTestId("save-btn");                          // no
+```
+
+Testing Library resolves roles from the accessible tree. Query that way and
+**a div-with-onClick fails the test** — accessibility stops being a review
+checklist item and becomes something the suite enforces.
+
+A `testID` proves a node exists. It proves nothing about whether a keyboard
+or a screen reader can reach it.
+
+Order of preference: role → label → text → `getByTestId` only for something
+genuinely not user-visible.
+
+## Assert accessibility, do not eyeball it
+
+Querying by role already fails a test when a control has no accessible name.
+axe covers what a role query cannot see — contrast, duplicate landmarks,
+orphaned labels, invalid ARIA — and all of it is mechanical, so a machine
+catches it every run instead of a human at review time.
+
+The stack wires two levels, and they see different things:
+
+```ts
+// component test — the mounted subtree
+import { expectNoA11yViolations } from "../test/a11y";
+
+await expectNoA11yViolations(screen.container);
+```
+
+```ts
+// e2e/a11y.spec.ts — the whole built page, already written for you
+const results = await new AxeBuilder({ page }).analyze();
+```
+
+Contrast against the real background, landmark structure and heading order
+only exist on the full page. A component test cannot see any of them, which
+is why both levels are there.
+
+`region` and `page-has-heading-one` are disabled for component tests: a
+mounted subtree legitimately has neither, and a rule that always fails
+trains people to ignore the report.
+
+See `.claude/skills/accessibility/SKILL.md` for what the rules mean.
+
+## The workbench is the render target
+
+`react-cosmos` fixtures are the same artefact used by design parity
+(`.claude/rules/design-parity.orchestra.md`). Write the fixture once: the
+component test renders it, and the parity check screenshots it.
+
+A fixture renders deterministically. A live screen carries real data,
+loading states and timing — differences that have nothing to do with the
+component.
+
+## E2E is about journeys, not components
+
+Three to five, against the **built** app, never the dev server. A dev server
+hides exactly what this layer exists to catch: a bad production bundle, a
+missing environment variable, a route that only resolves in development.
+
+`e2e/smoke.spec.ts` is written by the stack and asserts the app boots and
+throws nothing on load. Add: sign in and survive a reload; the one flow the
+product exists for; and that flow's failure path.
+
+Each one costs a build and a browser. A suite nobody trusts is worse than
+no suite.
+
+## Never
+
+- **Snapshot tests.** Enormous, unread, and "updated" reflexively. A
+  snapshot passes while the click handler stops firing.
+- **jsdom**, for anything about layout, visibility or focus.
+- Testing that the router routes, or that React re-renders. Assert that
+  pressing the control calls the thing with the right argument.
+- Chasing the coverage number through page composition files. The value is
+  in the logic modules, the components, and the journeys.
+
+## The build is part of the suite
+
+`tsc --noEmit` accepts a Next.js app that fails `next build` on a
+server/client boundary or a static-generation error. Neither tests nor lint
+load the bundler.
+
+The gate runs `build` for exactly this reason. When it fails, the fix is the
+code — never a loosened config.