decoupled-frontend

name	decoupled-frontend
description	Testing an SPA against a separate API — MSW handlers, async state coverage, factories.

Testing a Decoupled Frontend

Applies when the frontend is a separate deployable consuming a REST or GraphQL API it does not own. The API is a contract to be mocked faithfully, not an implementation detail to be stubbed away.

---

Detection

Signal	Meaning
API base URL in env (VITE_API_URL, NEXT_PUBLIC_API_URL, REACT_APP_API_URL)	Frontend talks to an external API
msw in devDependencies, or a mocks//handlers/ directory	MSW already adopted — extend it, do not add a second mocking layer
Generated API client / OpenAPI or GraphQL schema in the repo	Typed contract available — bind mocks to it
Backend and frontend in the same deployable (SSR templates, server actions only)	This skill does not apply

---

Mock at the Network Layer

Prefer Mock Service Worker (MSW) over mocking fetch/axios or the data-fetching library. MSW intercepts at the network level, so the component, the client, and the serialization all run as they do in production.

Handler rules

• Handlers must mirror the real API contract — if an OpenAPI spec or generated types exist, the mock response must satisfy them.
• Organize handlers by domain (handlers/auth.ts, handlers/orders.ts) so a test can override one domain without redefining the rest.
• Keep the default handler set on the happy path; express failures per test with server.use(...).

// Override for a specific test
server.use(
  http.get('/api/orders', () => HttpResponse.json({ error: 'Unauthorized' }, { status: 401 }))
);

• Reset overrides between tests (server.resetHandlers() in afterEach) so an error case cannot leak into the next test.

---

State Coverage — Mandatory for Every Async Feature

State	Must be tested
Loading	Skeleton / spinner visible while the request is in flight
Success	Data renders correctly
Empty	Empty-state UI shown when the response is [] or null
Error	Error message shown on 4xx / 5xx / network failure
Optimistic update	UI reflects the change immediately, and rolls back when the server rejects it

A feature with only a success test is not covered — the states users actually complain about are the other four.

---

Contract Awareness

• Mock responses drift silently. Type them with the same interfaces the production code uses: a type error in a handler is the drift alarm.
• When the backend renames or removes a field, the failing signal should appear in the frontend test suite, not in production.
• For stronger guarantees across teams, escalate to skills/testing/contract-testing/SKILL.md (consumer-driven contracts or schema validation in CI).

---

Test Data Factories

• Build objects with factories (e.g. fishery-style builders) rather than inline literals scattered across files.
• A factory takes overrides so each test states only what matters to it: buildOrder({ status: 'cancelled' }).
• Factories make edge-case variants cheap: long strings, null optionals, maximum item counts, missing optional relations.
• One factory per API resource, colocated with the handlers that return it — the factory and the mock stay in sync by proximity.

---

Selector Priority (Testing Library convention)

Priority	Selector	Use for
1	getByRole	Accessible role — button, textbox, heading
2	getByLabelText	Form controls with an associated label
3	getByText	Visible, stable text content
4	getByTestId	data-testid fallback — E2E and untargetable nodes
—	querySelector, CSS class selectors, XPath	Never

Reaching for a lower-priority selector is usually an accessibility signal: if no role or label can address the element, users of assistive technology cannot address it either — fix the markup instead of the test.

---

Visual Regression (Optional)

• Screenshot diffing or a component-explorer snapshot service is worth it for design-system-level components only.
• Do not apply it page-by-page — visual baselines are expensive to maintain and noisy on intentional change.
• Details: skills/testing/visual-regression/SKILL.md.

---

Before Declaring Done

• All five async states covered for every new async feature
• Handlers typed against the real contract; no any responses
• Default handlers are happy-path; error cases are per-test overrides
• server.resetHandlers() runs between tests
• No direct mocking of fetch/axios added alongside MSW
• Selectors respect the priority table