Testing Guide

Testing guide

Use this skill for test-specific decisions in this repository. The goal is useful regression coverage without letting test helpers, mocks, or component harnesses become a second application that is harder to maintain than the code under test.

For production-code design and testability seams, also use the code-quality-architecture skill. This guide owns test strategy, test helper conventions, and UI test escape hatches.

Core principles

• Test behavior and contracts that matter, not branches for their own sake.
• Prefer the smallest layer that proves the behavior: pure helper, service, controller, route/API contract, component boundary, then broader integration.
• Keep tests deterministic. Fake clocks, browser globals, filesystem/process/network boundaries, and hard-to-trigger errors when needed.
• Assert observable outcomes: return values, state transitions, emitted calls/events, HTTP responses, rendered user-facing state, or durable side effects.
• Avoid asserting incidental implementation details unless the selected gap is specifically about that implementation contract.
• Keep setup readable. A small explicit fixture is better than a magical factory that hides the scenario.
• Clean up global stubs, fake timers, DOM state, and pending promises so tests do not leak into one another.

Decide whether a test adds protection

Use three questions when adding or reviewing a test:

1. What meaningful failure does it catch?
2. What protection does it add beyond existing tests, required delivery steps, or normal usage?
3. What is the smallest boundary that proves the invariant?

Apply these as a review habit:

• Give each invariant one primary owner. For example, test validation cases at the service boundary and use a route test to prove HTTP wiring.
• Assign compilation to typecheck/build and packaging contracts to delivery checks against already-built artifacts, such as public declarations and deployment URLs.
• Rely on normal usage for obvious, recoverable workflow failures it reliably exposes. Automate protection where failures can escape notice, especially security, durable state, resource cleanup, and uncommon supported deployments.
• Use real processes, sockets, or browsers when their behavior is the invariant; for example, verify process termination with a real child process.
• Treat feedback time and fixture complexity as maintenance costs. Review slow additions and periodically consolidate overlapping coverage, preserving each meaningful invariant at its chosen boundary.
• Prefer small explicit fixtures and controllable collaborators. Keep review proportional to the change rather than adding mandatory forms or new testing infrastructure.

Choosing the test layer

Prefer this order unless the behavior requires a higher layer:

1. Pure helper/service tests for data shaping, validation, cache decisions, command construction, and conversion logic.
2. Controller/runtime adapter tests for state orchestration, endpoint selection, cancellation, timers, and injected collaborators.
3. Route/API contract tests for HTTP status mapping, path/query/body parsing, proxy allowlists, and compatibility contracts.
4. Component-boundary tests for UI event wiring and rendered state. Prefer real DOM/custom-element interaction via the per-file happy-dom harness (see Lit component tests).
5. Broad verification (npm run verify) when a change is cross-cutting, changes shared helpers/types, or before final merge review.

Do not jump to a broad UI or integration test just because it feels more realistic if a lower layer proves the same behavior with less noise and less flake risk.

Test helpers and fakes

• Keep helpers local until reuse is clear. If a pattern appears in multiple files, consolidate deliberately rather than copy-pasting variants.
• Type helpers and fakes strictly; avoid any unless the test is intentionally modeling an untyped external boundary.
• Fake only the boundary needed for the scenario. Do not mock the unit under test or so many collaborators that the assertion stops proving real behavior.
• Prefer controllable promises, fake timers, and explicit injected dependencies over sleeps or timing guesses.
• Name helpers after the domain behavior they support, not the mechanics of the fake.

Lit component tests

Test Lit components through public/component boundaries, choosing the narrowest seam that proves the behavior, in this order:

1. Pure exported seam for content, ordering, and composition logic: extract an exported pure function from the component (for example sessiondPanelNotices or chatQueuedMessageSections) and test that, rather than scraping rendered output.
2. happy-dom harness for rendered state and real user-like interaction (see below).
3. TemplateResult handler extraction only as a narrow legacy escape hatch (see its rule below).

happy-dom harness

happy-dom is the standard DOM environment for Lit component tests. It is a declared devDependency, opted into per file with a docblock on the first line of the test file:

// @vitest-environment happy-dom

Keep the opt-in per file; never set a global environment in vitest.config.ts. Pure logic tests stay on the fast default node environment, and only DOM-touching tests pay the harness cost.

Use the harness for what the node environment cannot provide and the extraction escape hatch forbids: rendered shadow-DOM state, real events (click(), dispatchEvent), focus and activeElement, native form semantics (radio/checkbox grouping, checked), and ARIA wiring such as aria-describedby or aria-live. Instantiate the component, set properties per its contract, append it to document.body, and interact with the rendered controls instead of invoking Lit handlers.

happy-dom is not a browser. Do not assert layout, styling, visual state, real scroll geometry, or IntersectionObserver/ResizeObserver behavior with it. Stub missing APIs at the boundary — spy on Element.prototype.scrollIntoView, stub window.matchMedia — and assert the calls, not geometry.

Conventions:

• Clean up in afterEach: document.body.replaceChildren() and localStorage.clear() so DOM and storage state do not leak between tests.
• Await element.updateComplete after property changes or events before asserting; await it twice when the component schedules another render from within updated(), so any follow-up render has settled.
• Assert user-visible rendered state or controller calls caused by the interaction, not Lit internals.