Write a spec

New specs are TypeScript (*_spec.ts). Do not add a new .js spec.

Browser (Testem + Mocha + Chai)

• Import describe / it / hooks from "mocha-globals" (Vite alias to tests/bdd-globals.js) and assert or expect from "chai". Render with global m.
• Thread catalog: CatalogReader and state: State. Use createCatalog(), createState(), and tests/browser-catalog-fixture.js (seedCatalog / seedCatalogWithGeneratedContext). Do not depend on the production catalog or bootstrap state. See catalog.
• seedCatalogWithGeneratedContext pulls in generated metadata, so run npm run dev or npm run build first or it resolves nothing.
• beforeEach / afterEach should create and remove DOM hosts.
• Import the new file from tests/tests.js. If you skip this, Mocha never runs the spec and Codecov patch fails with no test failure. A .ts spec is registered with its real extension (import "./foo_spec.ts";) — see typescript.

New .ts specs are type-checked: tests is in tsconfig.json include under @tsconfig/strictest, so run npm run type-check as well.

Example: Unit and component specs.

Node

Put the file under tests/node/. Import the implementation (.ts, or leftover .js). The runner collects *_spec.js and *_spec.ts automatically — no registry file.

How to run one file: run-one-spec.

Visual (Playwright)

Add cases under tests/visual/. Reuse waits in home-helpers.ts. Do not import the file from tests/tests.js. Visual tests are not Codecov-instrumented; Argos needs ARGOS_TOKEN. When a layout or CSS change warrants a run, and how to write one: visual-test. Isolated run: run-one-spec.

Confirm the new lines are hit

This is a full-suite run, not isolation. Skip if the path is in codecov.yml ignore:.

sources/ → npm run test:browser:coverage, then coverage/browser/index.html (or the terminal report).

scripts/ → npm run test:node:coverage, then coverage/node/index.html.

Which command, what the gates mean, and why comment-only diffs still pass: coverage. PR gates: CONTRIBUTING.md.