Fast Link testing

Protect observable contracts with the smallest maintainable test surface. Adapted from Eve's test-audit.

• For audits or cleanup, read Audit and cleanup.
• Apply the shared rules below to authoring and auditing.

Authoring gate

Inspect the production owner, callers, and neighboring tests. State:

• Contract: observable inputs and outcomes, with source evidence.
• Regression: name a production fault and trace the exact assertion it breaks.
• Placement: the test layer and failure existing tests cannot catch.

Keep exhaustive cases with their owner:

• Core: eligibility, event ordering, click suppression, cleanup.
• React: refs and controller lifecycle.
• Next: Link and region adaptation to App Router.
• Test adapter failures without replaying core's eligibility matrix.
• Keep observable ordering and counts that detect early or duplicate navigation, or broken cleanup.

Choose the surface

• Use the cheapest layer that exposes the regression.
• Read package scripts, Vitest configs, and turbo.json for environments and build prerequisites.
• Give each contract one primary test owner. Additional layers need a distinct failure to catch.
• Example: a spec checks the router's replace argument; a production fixture checks back-stack behavior.

Specs

• Prove decisions, controller state, adapter arguments, React rerenders, and cleanup.
• Colocate *.test.ts / *.test.tsx with the owner; root tooling uses scripts/**/*.spec.mjs.
• Package specs use Vitest's unit project in jsdom. Synthetic events prove supplied-event handling, not native activation.

Browser tests

• Prove native targeting, capture/bubbling, trusted press/release sequences, default navigation, and browser differences.
• scripts/browser/core.pw.mjs tests built core with Playwright Test cases in Chromium, Firefox, and WebKit.
• Use browser input for native activation claims; dispatchEvent remains synthetic in a browser.
• Keep cases whose browser boundary adds proof.

Real app fixtures

• Prove actual Next Link/router behavior, hydration, history, scroll, base paths, prefetch, and composed navigation.
• Extend fixtures/next-16 and scripts/browser/next.pw.mjs; keep the production app pinned.
• Router mocks cannot establish real framework behavior.
• Preserve fixtures/core to verify the built public core package in Node without framework or browser globals.
• Use fixtures/react to verify SSR through the built public React package without DOM globals.

Assertion value

• Exercise production behavior; derive expected outcomes independently from its contract.
• Reject self-comparisons, assertion-free probes, and expectations copied from the tested algorithm.
• Mock only the unavailable boundary; keep the asserted behavior real.
• A mock supplying its own asserted result proves setup. Next's hand-written Link/router mocks prove adapter wiring only (packages/next/src/testing/setup.ts).
• Give each test one scenario and enough assertions to distinguish its failure.
• Prefer exact outcomes over truthiness or existence. Avoid asserting a whole value and every field without a distinct failure to catch.
• Extend tables for equivalent input/output cases; keep distinct lifecycle or event sequences separate.
• Give each table row a meaningful boundary or failure.
• Test through the owning module or consumer so behavior-preserving refactors retain coverage.
• Keep helpers local; add production exports or options only for production needs.
• Check static contracts against the actual artifact structurally when runtime execution is impractical.
• Example: retain real release-workflow prerequisite guards. Synthetic mutations testing a test-local validator add no production proof unless it is production validation code.
• For bug fixes, observe failure on pre-fix behavior for the intended reason, then a pass after repair.
• Exclude unrelated exceptions, missing servers, or mock rejections as regression proof. Report unavailable pre-fix checks.

Setup and isolation

• Keep arrange, act, and assert visible.
• Share small setup helpers; leave scenarios and expectations at call sites.
• Prefer local setup over mutable suite state or helpers with many switches.
• Reset mocks, DOM, listeners, controllers, and browser resources for independent, order-insensitive tests.
• Use teardown or finally to clean up even after assertion failure.

Waits and browser runners

• Wait for observable readiness or completion with bounded timeouts.
• Use fake timers for timer contracts in specs.
• Before negative assertions, establish completion of the relevant event or operation.
• Explain the limits of necessary observation windows; elapsed sleep alone does not establish completion.
• Give browser scenarios separate identities and fresh contexts where state can leak.
• Share builds and production servers when appropriate.
• Use Playwright Test fixtures and locator assertions for browser scenarios.
• The Next global setup reuses startFixture; preserve one production server per invocation and the benchmark consumer.
• See browser suite commands and diagnostics.

Coverage

• Use uncovered branches to find missing contracts; executed lines alone do not prove behavior.
• Run pnpm coverage to measure package production files with the configured V8 provider; inspect includes and exclusions before interpreting results.
• Base scoped thresholds on that baseline and risk. Avoid invented percentages or assertions added to satisfy a number.
• Report measurement limits. A missing threshold alone is not a test-quality defect.

Verify and report

• After edits, run focused owner tests, then required pnpm validate.
• Follow root AGENTS.md for release and tarball checks when public packages change.
• For read-only advice or review, report the checks supporting each conclusion.
• Report commands, observed results, and untested browser/app contracts.
• Keep mocked or skipped checks distinct from real-browser and production-app proof.