Unit Tests (bklit-ui)

Read this skill before proposing or writing tests. Default stance: fewer, higher-signal tests.

When to add tests

Add tests when they lock in behavior that is easy to break silently:

Worth testing	Why
Pure functions / modules	Stable inputs → outputs; fast; no DOM
Formatters, parsers, scale math, bounds	Regression on string/number output is user-visible
Codegen / export / registry helpers	Output shape is the contract
Non-obvious edge cases	Empty data, reversed ranges, clamping

Examples in this repo: chart-formatters.test.ts, highlight-segment-bounds.test.ts, animation.test.ts, apps/web/lib/studio/__tests__/*.

When NOT to add tests (unless explicitly requested)

Do not add tests just to increase coverage or “be thorough”:

Skip	Why
React component render smoke tests	visx, motion, portals → brittle; manual/docs check is cheaper
`memo()` / guard extractions (#65-style)	Structural perf refactors; output unchanged; RTL mount assertions are heavy
Default prop passthrough	`formatValue = intFmt` — types + formatter tests cover it
Third-party library behavior	Don’t re-test d3, visx, or React
Trivial getters / one-line wrappers	No regression signal
Snapshot entire chart SVG/JSX	High churn, low signal

If the user asks “should we test X?” — say no when X falls in this table, and suggest a lighter alternative (pure helper test, manual check, CI build).

Repo conventions

Runner: Node built-in test runner + tsx (not Jest/Vitest unless the repo adopts them later).

pnpm test              # root — turbo runs packages with a test script
pnpm --filter @bklitui/ui test
cd apps/web && pnpm test

Place tests: **/__tests__/**/*.test.ts next to the code under test.

Pattern:

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { myFn } from "../my-module";

describe("myFn", () => {
  it("handles empty input", () => {
    assert.equal(myFn([]), expected);
  });
});

Equivalence tests (preferred for formatters): assert shared module output matches the previous inline call (e.g. toLocaleDateString with same locale/options) so tests stay timezone-safe and prove no visual regression.

New package test script: add to package.json:

"test": "node scripts/run-tests.mjs"

Use a small scripts/run-tests.mjs that collects *.test.ts from __tests__ and invokes node --import tsx --test — shell globs break on Linux CI. Add tsx as a devDependency if missing. Wire into root turbo.json test task; CI runs pnpm test.

Decision checklist (run before writing)

Is the logic pure or extractable to pure functions? → Test that. Consider extracting first.
Would a test fail on a real user-visible bug? → Good candidate.
Does it need jsdom / RTL / Playwright? → Stop; justify to user or defer to manual/visual check.
Did the user ask for tests? → Still apply this skill; don’t over-deliver.
How many cases? → 3–10 focused cases, not exhaustive matrices.

What to tell the user

When recommending tests, be explicit:

Add: “Test chart-formatters.ts — pure, high regression value.”
Skip: “Skip component tests for the memo split — no output change; build + manual chart docs are enough.”
CI: Mention pnpm test in PR test plan when adding or changing tests.

Anti-patterns

Adding Jest/Vitest/Testing Library for a one-off without team buy-in
Mocking entire chart context to assert useMemo call counts
Testing implementation details (hook order, internal component names)
Duplicating type-checker work (expect(typeof x).toBe('function'))
Committing tests that only pass locally due to hard-coded timezone/locale strings

unit-tests