Frontend Test Conventions

Load write-frontend, plus write-svelte for Svelte targets and write-design-system for uikit. Read the production behavior before writing tests. Read neighboring tests and the official documentation for the installed testing tools. Preserve existing tests unless the behavior they specify has been intentionally removed.

Timing

Follow develop-feature. Early stories make a draft reviewable; early tests should only resolve uncertainty, reproduce a defect, or protect a risky invariant. Complete the behavior matrix and full relevant regression suite after issue scope is approved. These conventions govern the quality of any test written at either stage, without requiring exhaustive coverage during exploration.

Test at the nearest truthful layer

Use the smallest layer that proves the user-visible contract:

1. Test pure parsing, formatting, and state transitions as unit tests.
2. Test component rendering and interaction through the DOM with Testing Library.
3. Use Storybook stories as the exhaustive catalog of reusable component states; add interaction and accessibility assertions where supported.
4. Use real-browser end-to-end tests for routing, focus across pages, browser APIs, hydration, multi-component journeys, and behavior an emulated DOM cannot prove.

Do not duplicate the same assertion at every layer. Keep one strong contract test and add broader tests only for integration risks.

User-centered assertions

• Query elements by accessible role and name first, then label, text, or other user-visible meaning. Use test IDs only when no semantic query exists.
• Interact as a user would: focus, type, click, submit, and press keys. Do not call component methods or mutate internal state to reach a condition.
• Assert observable output, accessible state, navigation, focus, and network contract. Do not assert private classes, framework internals, reactive calls, or implementation sequence.
• Use async queries for async UI. Wait for the condition the user observes, not an arbitrary timeout.
• Cover keyboard behavior and focus order for every custom interaction pattern.
• Prefer explicit assertions over broad snapshots. Use a snapshot only for a stable serialized contract whose meaningful review is easier as a whole than as targeted assertions.

Behavior matrix

Cover the states relevant to the changed contract:

• Default, supported variants, and boundary values.
• Loading, empty, error, retry, stale, and success.
• Disabled, readonly, required, invalid, expanded, selected, and pressed states where applicable.
• Text shorthand, composed snippets, and omitted optional regions for reusable content APIs.
• Keyboard-only operation, focus entry/exit, and focus restoration.
• Long text, missing optional content, localization, RTL, narrow viewport, and zoom/reflow.
• Dark theme, forced colors, reduced motion, and contrast-sensitive states for shared UI.
• Variant-by-state comparisons on every materially different backdrop: canvas, opaque island, translucent surface, popover, and dialog where applicable.
• Cancellation, out-of-order responses, and duplicate submission for asynchronous actions.

Do not manufacture cases that the public contract cannot reach.

Isolation and doubles

• Keep tests deterministic and independent of order. Restore timers, globals, storage, fetch mocks, and DOM mutations after each test.
• Mock at system boundaries, not inside the unit under test. Prefer a lightweight fake with behavior over a deep mock that repeats implementation details.
• Use real parsing, validation, and component composition when inexpensive. Over-mocking creates a test for the mock graph rather than the product.
• Control clock, randomness, locale, and network explicitly when they affect output.
• Use framework-supported request interception for network tests. Never call a live third-party service from unit or component tests. The unit project of nodelib-config's SvelteKitVitest runs offline: its global fetch rejects every request a test does not stub, and vi.unstubAllGlobals() restores that rejection.
• Make mock failures loud: reject unhandled requests and unexpected calls.
• Build a fresh Response per call (mockImplementation(async () => Response.json(…))). A body reads once, so mockResolvedValue(response) hands every later call a consumed body, and the failure looks like a parsing bug in the code under test.
• Pin performance contracts with direct assertions. To prove a body is released, keep the stubbed Response and assert response.bodyUsed after the call. To prove calls run in parallel, return a promise that never resolves and assert synchronously that every independent call has started. A serial loop then fails at once instead of timing out.

Vitest and Testing Library

• Use Vitest APIs documented for the installed version. Prefer typed dynamic module paths when a module mock is genuinely necessary.
• Give every Vitest project config file an explicit root: fileURLToPath(new URL(".", import.meta.url)). Since Vitest 5.0.4, a project gets its root after svelte() has read it. Without one, the plugin starts from the workspace root, leaves Svelte libraries untransformed (Unknown file extension ".svelte") and loads a second Svelte runtime (lifecycle_outside_component).
• Name a config that holds only Vitest options vitest.config.ts, never vite.config.ts. Since 4.7.7, svelte-check reads .svelte files from symlinked workspace packages at their real path and configures each from the nearest vite.config.* or svelte.config.*, the Vite one winning within a directory. A Vite config without the Svelte plugin then fails with No Svelte configuration found in vite config, as uikit's packages/storybook-config did. Vitest tries vitest.config.* first, so the rename costs nothing.
• Keep vi.mock scope and hoisting rules visible. Refactor an inseparable module boundary rather than relying on a mock the runtime cannot intercept.
• Render DOM, not component instances. Follow Testing Library query priority and guiding principle: tests should resemble real use.
• Use the repository user-interaction helper when present. Reserve low-level event dispatch for the browser primitive being tested.
• Put native lifecycle and teardown races in a browser project, not jsdom. Exercise the real element API and event queue, including events delivered as a component unmounts, and assert the user-visible outcome rather than Svelte internals.
• Name tests as observable behavior in plain language. Group by public function, component, or user journey.

Storybook

• Give every public component stories for meaningful variants and states, including interactive, disabled/error, long-content, and narrow-layout cases.
• Show related variants together. Include the concise text API and one realistic composed example; verify that optional regions can be omitted without leaving empty structure or spacing.
• Render sizes, colors, variants, and persistent/transient state combinations in aligned matrices. Keep docs wrappers interaction-neutral so table or tile hover styles cannot masquerade as component behavior.
• Keep stories deterministic, self-contained, and free of production side effects. Use loaders and decorators only for shared, explicit environment contracts.
• Use realistic interface content in visual examples. Explain controller transitions and keyboard mechanics in docs and tests instead of making them the example's title or body.
• Isolate screens and top-layer content in subdocuments on docs pages. Show desktop/mobile examples together with responsive wrapping; modest scaling helps comparison, but verify geometry and touch targets at the native viewport size. Check the docs page itself as well as individual stories.
• Pin visual-review stories through fixed-state controllers. Clicking, submitting, pressing Escape, or clicking outside must not change the displayed scenario. Show distinct states as separate examples; exercise live transitions in controller/component tests. Keep locale, theme, and story inputs configurable instead of duplicating scenarios per locale. Preserve native focus, scrolling, and text selection; do not freeze previews with event-blocking overlays, inert, or pointer-events: none.
• Add a docs page for every public component: intent, composition, accessibility contract, and examples. Use generated controls and ArgTypes for API reference instead of repeating a manual table. Document foundations separately from components.
• Enable accessibility analysis globally and make violations fail automated story tests when the installed Storybook integration supports it. Any exception must identify a documented false positive or intentional antipattern story.
• Run contrast assertions in the real browser against the exact rendered semantic pairs and states, not palette swatches alone. Automated tooling does not credit glow and may not understand every gradient, transparency stack, pseudo-element, or forced-colors result; inspect computed output and visually compare state separation in the supported surface contexts.
• Treat a near-threshold contrast violation as a real failure. Fix the owning semantic token and keep a rendered safety margin; do not disable the rule or add a consumer override merely because a calculated source value appeared to meet the minimum.
• Treat automated accessibility output as a first pass. Manually verify keyboard/focus behavior and relevant browser/assistive-technology combinations for complex widgets.
• Keep stories and docs in a private workbench. Keep reusable Storybook theme, preview, and test configuration in a separately consumable development package; never publish stories or runtime workbench code as part of the component package.
• List each dependency subpath a story imports in Storybook's optimizeDeps.include (@a-novel-kit/uikit-storybook/ScrollPreview.svelte, not only the package). Vite matches entries exactly; an unlisted subpath is optimized mid-run, which reloads the iframes and fails every story file on a cold cache. CI is always cold, so prove such fixes after deleting node_modules/.cache and node_modules/.vite.
• Keep a representative framework or extraction fixture with the shared nodelib preset it validates. A platform tests its product catalogs, screen states, and wiring instead of copying that generic fixture locally.

End-to-end tests and screenshot comparisons

During stage 3 of develop-feature, create or update all affected Playwright tests for client-side work. Cover the changed journeys and browser contracts, then run the relevant browser suite. Reuse the existing harness; when one is missing, include the smallest suitable Playwright setup in the agreed scope, following choose-dependency. Do not silently defer required browser validation.

Separate a journey's phases with blank lines. When a loop wraps test.step, move the step body into a named function, so the loop reads as the list of cases.

For rendered changes, capture deterministic screenshots of the affected states and supported viewports and compare them with reviewed baselines. Stabilize data, fonts, locale, theme, and motion. Inspect expected, actual, and diff images. Fix unexpected differences; update a baseline only when the new rendering matches the agreed UI, and review initial baselines for new screens. Screenshots complement live app/Storybook review and behavioral assertions. For non-visual client changes, verify relevant existing visual baselines where applicable and state when no rendered surface is affected instead of inventing a screenshot test.

• Test critical journeys and browser contracts, not every visual variant.
• Use accessible locators and observable readiness conditions. Never use fixed sleeps.
• Keep test data isolated and clean it through supported product interfaces.
• Point every URL the server under test reads at a local fixture started in a global setup, never at a live or production file. When the server caches what it reads, give each state its own webServer entry: entries start in order, so later ones run node build on the first entry's build. platform-studio's downtime journeys follow this pattern.
• Make a compose service that a journey stops and starts, as the outage journeys stop authentication, join a holder's network: network_mode: service:<holder>, where a registry.k8s.io/pause holder publishes the ports. A restarted container otherwise gets a new host interface, and Chromium fails the page then loading with net::ERR_NETWORK_CHANGED. platform-template's builds/compose.e2e.yaml follows this pattern.
• Serve another platform's production image over plain http with PROTOCOL_HEADER: x-forwarded-proto on its container, and send X-Forwarded-Proto: http from the journeys' browser (Playwright extraHTTPHeaders). adapter-node otherwise assumes https, and SvelteKit then rejects every form post to that platform as cross-site. The account platform also names an https issuer, which its clients refuse.
• Run Authentication in a platform's stack with the callers production gives it. service-authentication's service-token-issuer image stands in for the cluster's issuer, which Authentication trusts through SERVICE_TOKEN_ISSUER, SERVICE_TOKEN_AUDIENCE and SERVICE_TOKEN_CALLERS. A Playwright global setup draws the platform's token from the issuer into the file SERVICE_TOKEN_PATH names. Fixtures call Authentication through a fetch that adds a caller's token from the issuer in X-Service-Authorization.
• Run the account platform's image in a client's stack, with a token drawn from the issuer at start, and register the client in OAUTH_CLIENTS on the address of the journeys' server. The account platform's own stack registers a stub client instead, whose callback the test serves and whose code the test exchanges. platform-studio's builds/compose.e2e.yaml and tests/e2e/service-token.ts follow this pattern.
• A change to a platform's shell or pages can break the sibling journeys that drive its published image, and they fail only when that image's pin moves. Search every other platform's tests/e2e/ for each accessible name you move or remove, and fix the journeys that reach it in a pull request that also bumps their pin. platform-account v1.2 moved its "Agora apps" list into the rail, and Studio's sign-in journey, still clicking the removed button, broke Renovate's account image bump until platform-studio#439.
• A page.route handler sees only the first URL of a redirect chain. To alter a later step, walk the chain with page.request.get(url, { maxRedirects: 0 }), read each location, and open the altered URL with page.goto. platform-studio's failed-exchange journey forges its code this way.
• Capture traces/screenshots on failure where the existing runner supports them; do not commit transient artifacts.
• Run at least the repository browser baseline for compatibility-sensitive behavior.

Before a repository first compares its screenshots against Drive reference batches, read Subscribe a repository to Drive visual tests for its identities, folders, variables and seeding order. Read its recovery section when master's test-browser keeps failing on screenshot changes that merged pull requests already approved.

A Vitest browser project, such as uikit's Storybook stories, compares its screenshots against Drive reference batches through node-actions/test-playwright with runner: vitest. The workflows repo's docs/migrations/v1.64.0.md is the adoption guide. Vitest's browser mode adds these rules:

• Capture expect(page).toMatchScreenshot(). Modal dialogs and popovers render in the top layer, outside every container, so a container capture misses them. In Storybook's Vitest run, the first body div is the hidden sb-preparing-story wrapper.
• Declare each screenshot with a visual-snapshot annotation in beforeEach or before the first assertion. Vitest accepts annotate() only while the test state is run, and rejects it in afterEach or after a failed soft assertion.
• Name each screenshot flat, from [A-Za-z0-9_-] with single hyphens: `${task.file.name}-${task.name}`.replace(/\W+/g, "-"). Vitest resolves only the base name and strips every other character, so a Storybook story ID or a dotted name stops matching its annotation.
• Treat the annotations as the inventory. Vitest records a toMatchScreenshot artifact only on failure, so the Drive runner lists screenshots from annotations and fails a run that writes an undeclared one.
• A style assertion in a play function turns a visual change into a functional failure, which allow-screenshot-change cannot waive. uikit's Toolbar story asserts that its link keeps the button radius, so a Button radius change fails until the link follows.

Coverage and completion

Treat coverage as a map, not a percentage target; 100% is not required. Missing error, keyboard, security, or state-transition paths matter; uncovered generated glue does not justify a test.

Run focused checks during iteration. After scope approval, complete meaningful coverage and run the applicable suites; after cleanup, rerun checks affected by the final edits:

pnpm lint
a-novel test --type=pnpm -y
a-novel build --type=pnpm -y

The change is complete only when new behavior has a regression test at the truthful layer and all affected existing tests remain green.