Web unit testing

Web Unit Testing

Purpose

Plan the unit-test layer: fast, deterministic tests for pure logic — utilities, hooks, reducers/stores, validation schemas, data mappers — under the app's chosen runner. One layer of the strategy from ../../testing-strategy; component and E2E layers sit above it.

When to Use

• When setting up the testing foundation for a web app.
• When business logic accumulates untested, or unit tests have become slow/flaky/DOM-entangled.
• Not for rendered-component behavior (web-component-testing) or user journeys (playwright-e2e).

Inputs

• Framework foundation (Vite → Vitest is the natural fit; Next.js → Vitest or Jest, decided once).
• The logic inventory: where non-trivial pure logic actually lives.
• CI expectations (../../testing-strategy, web-deployment).

Discovery Questions

• Which modules hold real logic worth unit coverage (pricing, parsing, permissions mapping, schema rules)?
• Runner decision: Vitest or Jest — what does the stack make natural, and is there an existing investment?
• What's the colocation/naming convention (*.test.ts beside source is the default)?
• What runs on every push vs pre-merge (speed budget for the unit layer)?

Responsibilities

• Select the runner with justification (Vitest default on Vite for config unity and speed; either works on Next.js — don't run both).
• Define what belongs in this layer: pure functions, hooks (via testing-library's hook utilities where needed), store/reducer logic, Zod/schema validation rules (web-forms), API error mapping (web-api-integration) — no DOM assertions, no network.
• Set conventions: colocated files, clear naming, Arrange-Act-Assert, one behavior per test, table-driven cases for rule matrices.
• Keep tests deterministic: fake timers/dates where time matters, no real network/fs, seeded randomness.
• Wire into CI as the fast always-on layer; keep the suite fast enough that nobody skips it.
• Target coverage where logic lives — business rules and edge cases — not a blanket percentage chased through trivial files.

Required Workflow

1. Confirm the runner with the foundation skill's stack decision.
2. Inventory logic-bearing modules; rank by risk.
3. Define conventions (location, naming, determinism rules).
4. Plan coverage for the ranked inventory, edge cases first.
5. Wire into CI; record what's covered and what's deliberately not.

Decision Rules

• If a test needs the DOM, it's a component test — move it up a layer.
• If a test needs a real network or service, it's not a unit test — mock at the module edge or move it up.
• Extract logic out of components to make it unit-testable, rather than testing it through renders.
• A regression test accompanies every logic bug fix (../../bug-investigation).

Rules

• Unit tests run in CI on every push; a red unit suite blocks merge.
• No snapshot tests as a substitute for asserting behavior.
• Test names state the expected behavior, not the function name.

Anti-Patterns

• Chasing a coverage percentage through index files and type re-exports.
• Unit tests that render half the app to check a formatting function.
• Mock setups so heavy the test verifies the mocks.
• Flaky time/locale-dependent tests nobody trusts.

Validation Checklist

• Runner selected with justification; single runner for the layer.
• Logic inventory ranked; layer boundaries respected (no DOM/network).
• Conventions defined (colocation, naming, determinism).
• Edge-case coverage planned for risk-ranked modules.
• CI wiring defined; suite speed acceptable.

Definition of Done

A recorded unit-testing plan — runner choice, layer boundaries, conventions, risk-ranked coverage targets, and CI wiring — producing a fast suite the team runs constantly and trusts.

Related Skills

../../testing-strategy, web-component-testing, playwright-e2e, web-forms, web-api-integration, ../../bug-investigation, vite-react-foundation, nextjs-foundation.

Related Knowledge

../../../knowledge/ (business rules worth encoding as tests).

Related References

../../../references/web/testing/ (conventions, examples — when populated).

Context Loading Guidance

• Requires: stack decision, logic inventory, CI expectations.
• Does not require: UI component detail, deployment specifics.
• May load: web-component-testing to draw the layer boundary precisely.
• Stop when: the plan and conventions are recorded.

Token Efficiency Guidance

Rank modules by risk in a short table; don't enumerate every function. Conventions stated once govern the whole layer.