Web component testing

Web Component Testing

Purpose

Plan the component-test layer: rendered components exercised the way users interact with them — accessible queries, real events via user-event, network mocked at the boundary with MSW — asserting behavior, not implementation detail. Sits between web-unit-testing and playwright-e2e.

When to Use

• When components carry interaction logic worth verifying (forms, tables, dialogs, gated UI).
• When existing component tests are brittle (implementation-coupled, snapshot-heavy) or missing.
• Not for pure logic (web-unit-testing) or cross-page journeys (playwright-e2e).

Inputs

• The component inventory, prioritized by interaction complexity and risk.
• Unit-layer runner decision (web-unit-testing) — component tests share it (jsdom environment).
• API shapes for MSW handlers (web-api-integration).

Discovery Questions

• Which components have behavior worth testing (conditional rendering, validation UX, async states) vs purely presentational?
• What shared render setup is needed (providers: theme, router, query client)?
• Which API interactions should MSW model, and where do handler defaults live?
• What genuinely needs a real browser (layout, CSS, focus subtleties, portals under real stacking) — and is therefore E2E scope?

Responsibilities

• Set the query discipline: getByRole (with accessible name) first, then label/text; data-testid as the escape hatch — this makes tests double as accessibility probes (web-accessibility).
• Use user-event for interaction (typing, clicking, keyboard) over firing synthetic events directly.
• Mock the network at the boundary with MSW: shared handler defaults mirroring real API shapes, per-test overrides for error/empty/slow cases — components don't get their fetch layer stubbed internally.
• Test behavior contracts: what renders for which state (loading/error/empty/data), what happens on interaction — never internal state, hooks call counts, or DOM structure incidentals.
• Provide a shared render helper wrapping required providers so tests stay terse and consistent.
• Constrain snapshots to small, intentional cases (if any); assert specifics instead.
• Cover async UX properly: findBy*/waitFor instead of arbitrary sleeps; assert accessible loading/error states (web-error-handling).

Required Workflow

1. Prioritize components by interaction risk.
2. Build the shared render helper + MSW handler baseline.
3. Write behavior tests per priority component, covering data/loading/error/empty and key interactions.
4. Route real-browser concerns to playwright-e2e explicitly.
5. Wire into CI beside the unit layer; record coverage decisions.

Decision Rules

• If the assertion needs getByRole gymnastics because the component isn't accessible — fix the component, not the query.
• If the test breaks when internals refactor without behavior change, it's testing the wrong thing.
• jsdom can't verify real layout/painting/focus edge cases — don't fake it; escalate that case to E2E.
• Empty/error states are test cases, not afterthoughts.

Rules

• Component tests run in CI on every push with the unit layer.
• No mocking of the component under test's children by default — mock boundaries (network, time), not the tree.
• Deterministic: MSW-controlled responses, fake timers where needed, no live endpoints.

Anti-Patterns

• Snapshot files nobody reads, regenerated on every diff.
• Asserting on CSS classes/DOM structure instead of user-visible behavior.
• Stubbing fetch/axios per test instead of MSW at the boundary.
• Re-testing every prop permutation better covered by a unit test of the logic.

Validation Checklist

• Components prioritized by interaction risk.
• Shared render helper + MSW baseline planned.
• Query discipline (role-first) and user-event usage set as convention.
• Data/loading/error/empty states covered for priority components.
• Real-browser cases explicitly routed to E2E.
• CI wiring recorded.

Definition of Done

A recorded component-testing plan — priorities, shared setup, MSW boundary, role-first query conventions, and state coverage — yielding tests that survive refactors and double as accessibility checks.

Related Skills

web-unit-testing, playwright-e2e, web-accessibility, web-api-integration, web-error-handling, web-forms, ../../testing-strategy.

Related Knowledge

../../../knowledge/ (interaction-critical components).

Related References

../../../references/web/testing/ (render helper, MSW patterns — when populated).

Context Loading Guidance

• Requires: component priorities, API shapes, unit-layer decisions.
• Does not require: deployment detail, full source tree.
• May load: web-accessibility for query/name expectations; playwright-e2e for the layer boundary.
• Stop when: conventions and priority coverage are recorded.

Token Efficiency Guidance

Define conventions and the shared setup once; per-component plans are one line each (component → states → interactions).