Skip to content

README.md

Latest commit

 

History

History
79 lines (58 loc) · 2.9 KB

README.md

File metadata and controls

79 lines (58 loc) · 2.9 KB
Raw

Askr Test Suite Architecture

Askr tests are split by the runtime guarantees they need. Choose the lowest layer that can prove the behavior.

Layers

  • tests/unit: pure logic and isolated framework internals. These tests run in Node, must not touch document, window, browser element classes, jsdom, or Playwright.
  • tests/jsdom: DOM-like component behavior that does not need layout, paint, real focus, browser timing, or CSS engine behavior.
  • tests/browser: user-centric real-browser behavior such as routing, hydration, focus, keyboard flow, overlays, browser event loop behavior, and CSS-sensitive UI. Browser performance coverage lives here.

Shared test harness code lives outside the suite layers:

  • test-utils/fixtures: reusable components and scenario data.
  • test-utils/render: jsdom render helpers and scheduler observation helpers.
  • test-utils/playwright-app: the browser benchmark and scenario app that tests/browser imports.
  • test-utils/router, test-utils/hydration, test-utils/perf: reserved for layer-specific helpers as coverage grows.

Everything under test-utils/ is typechecked by test-utils/tsconfig.json, and benches/ by benches/tsconfig.json. npm run typecheck (and therefore npm run lint) runs both alongside the src typecheck.

Running Tests

npm test
npm run test:unit
npm run test:jsdom
npm run test:browser

npm test runs the full local test matrix: unit, jsdom, and the browser suite.

Layer Rules

Unit tests cover router matching, route params, guards, reactivity, scheduler internals, render/diff primitives, compiler helpers, serialization utilities, error handling, and public API edge cases. Prefer table-driven cases and failure paths.

jsdom tests cover component rendering, event wiring, simple DOM updates, form/input behavior, conditional/list rendering, lifecycle behavior, and basic hydration tests. Do not use jsdom for layout, paint, animation, browser timing correctness, or realistic focus behavior.

Playwright tests cover behavior that needs an actual browser. Use semantic locators or data-testid consistently, avoid fragile timing assertions, and let traces on failure capture debugging context.

Accessibility tests run in Playwright with axe. Treat automated scans as a baseline, then add semantic and keyboard assertions for the specific interaction being covered.

Benchmarks

Benchmarks live outside tests:

  • benches/tier1: hot path benchmarks.
  • benches/tier2: subsystem benchmarks.

Both lanes run in Node and jsdom. Run them with:

npm run bench
npm run bench:tier1 -- --outputJson bench-results/tier1.json && npm run bench:tier2 -- --outputJson bench-results/tier2.json

Enforcement

tests/unit/dev_checks validates suite conventions, layer boundaries, browser runtime env access, JSX syntax, and benchmark category rules. If a new test needs a higher layer, move the test rather than weakening the rule.