typescript-unit-testing

TypeScript unit testing rules

"Do" and "Do not" are hard rules. "Prefer" states the default and allows a justified exception. "May" grants a permission. Copy the Good form.

Every case must discriminate the behavior named in its title: a wrong implementation makes the assertion fail. A test with weak assertions costs all the maintenance of a test and gives none of the protection.

Tools

Use node:test for the runner, lifecycle, and the context's t.mock (stubs, spies, fake timers); node:assert/strict for assertions; strong-mock for strict interaction mocks; --experimental-test-coverage for coverage.

import assert from 'node:assert/strict'
import { describe, test } from 'node:test'
import { mock, verify, when } from 'strong-mock'

Do not add another runner, assertion library, or mocking library. Do not import the process-wide mock from node:test; use the context's t.mock.

Pairing and coverage

• Every production .ts module under extensions/pi-claude-marketplace/ has exactly one .test.ts module under tests/ at the mirrored path: extensions/pi-claude-marketplace/orders/order-service.ts -> tests/orders/order-service.test.ts. That test module owns the source module's exported behavior.
• No exclusions. Type-only modules, index.ts barrels, and one-function modules all need a test module. If a module is not worth a test, fold it into its consumer.
• Do not co-locate tests under extensions/pi-claude-marketplace/, use .spec.ts, or test one source module from another module's test.
• Test modules and test support (fakes, seeds, contracts) need no meta-tests; a fake is verified through its shared contract.
• Each source-test pair reaches 100% function, line, and branch coverage when run alone. Aggregate coverage does not count.
• Do not add coverage exceptions or /* node:coverage ignore */ directives. Remove dead code or cover it through a public-behavior case.
• Run node --test <test-path> while developing, npm run test:coverage:direct -- <path> for the pair (:all after a shared contract, fake, or harness change), and npm run check before completion.