Testing Conventions
Apply when writing or reviewing tests.
What to test
Test when code has: parsing/transformation logic, security boundaries, business rules with arithmetic, state machines, non-obvious edge cases, or CRUD paths with auth, tenancy, validation, serialization, uploads/downloads, or other side effects. Skip: shallow CRUD handlers with no meaningful branching, library wrappers, layout components, constants.
Prefer invariants over examples
When the input space is large (parsers, document transforms, normalization, sorting/filtering, security boundaries, Unicode-heavy logic), start by asking what must always be true, then encode that as a property test, fuzzy test, or adversarial regression test. Reach for ordinary example tests when they communicate a business rule more clearly than a property.
Good property/fuzz targets in Stella: DOCX/OOXML roundtrips, template/block-directive parsing, filename and header sanitization, search/filter/sort helpers, tenant-scope enforcement, and error normalization.
Structure
Colocate foo.test.ts next to foo.ts. For frontend, default
to extracting logic into foo.logic.ts and test that in Bun.
Use Playwright for browser-only behavior: auth redirects, route
guards, uploads/downloads, keyboard/focus, drag/drop, and
viewer/editor flows. Structural invariant tests (auth
enforcement, branded types) live in
apps/api/src/tests/security/.
Rules
Describe tests by behaviour, not by function name; prefer plain fakes over
mocking libraries for simple cases; and skip shallow examples that only raise
coverage when a stronger invariant test covers the same surface. Run tests
through the owning package script so preloads and setup survive:
bun run test -- --bail -t "<name>".
- Use
bun:testfor unit, invariant, and integration tests; use Playwright for browser behavior. Do not add another test runner without a clear gap Bun and Playwright cannot cover. [review] - Avoid hidden shared mutable state. Prefer per-test setup; use
beforeEachonly for deterministic reset, and use expensive shared fixtures only when explicit and isolated [review] - Assert observable behavior or an invariant, not the implementation sequence. A test that only proves "does not throw" or re-encodes the production algorithm needs a stronger assertion. [review]
- Use snapshots only when the serialized output is itself a stable, reviewable contract. Do not use snapshots as a substitute for behavioral assertions. [review]
- Test tenant isolation and ownership-source rules at the highest meaningful layer, not only as pure helper tests [review]
- Every bug fix needs a durable guard, but not necessarily an example test: prefer types, derivation, schemas, lint rules, or broader invariants when they eliminate the bug class [review]
- Guard the invariant, not the accident. Do not memorialize a one-off typo, stale literal, or incidental implementation detail in a dedicated test when structural coupling makes that failure impossible [review]
- Verify a new regression test fails against the known-bad behavior before trusting it. A test that never reaches the fault, or matches zero tests, is not a guard. [review]
- Detector and backstop tests use production-shaped inputs the detector can actually match. Assert the fixture reaches or differs on the fault boundary before asserting the protected outcome. [review]
- Where a map declares paths or cases, assert the declared and exercised sets
are equal in both directions. Pin fixture literals that stand in for producer
output with
satisfiesagainst the producer's return type. [review] - For systemic bugs, test the class: fixed points for replay, matrices for tenant isolation, properties for parsers/normalizers, state-machine transitions for lifecycle code, and round trips for serialization. [review]
- Keep time, randomness, network, filesystem, and database ownership explicit in tests. Pin or inject them rather than relying on ambient machine state. [review]
Mutation check
A test guarding behavior X is finished only once reverting X makes it fail. Until you have seen it go red against the known-bad behavior, it may be passing for an unrelated reason. When the test is the evidence for a fix, say in the PR that you ran the mutation and what it broke.
The usual failure is a fixture the fault cannot reach. Assert the fixture
DIFFERS before asserting the equivalence: check
expect(NFD(word)).not.toBe(NFC(word)) before asserting both normalize alike,
so a fixture that is already normalized cannot make the test vacuous.
Cross-runtime contracts
Where one rule lives in two runtimes at once (JavaScript, Postgres, the search engine), parity is proven only by DERIVING the other side's rules executably: query the live extension for its token output, render the SQL the query layer emits and assert on that, read the analyzer's configuration tuple.
A hand-maintained list mirroring the other side's behavior is not evidence of parity. It is the drift, written down: it agrees with the other runtime exactly until that runtime changes, and nothing fails when it does.
Projection census
Any "marked done" flag that mirrors state in an external system (search index, object store, queue) ships with a reconciler that compares both sides and reports the difference. Acceptance by the remote system is not durability, so the flag alone can never prove the projection landed.
Treat the reconciler as part of the feature, not follow-up work: without it the first divergence is invisible until a user reports missing data.
Property failure discipline
Use assertProperty(id, property, params?) from @stll/property-testing for
new properties; give it an explicit stable id matching the test title so the
printed bun test -t command selects the property. Keep arbitraries beside the
code under test. PR and merge-queue runs use deterministic seeds; exploratory
runs belong to the private nightly tier.
A failing seed is a real bug: fix it, then pin the seed and counterexample path
in packages/property-testing/property-seeds.json after the fix merges. Extend
the generator or oracle to cover the input class. Never rerun until green.
Use neutral public seed notes; report sensitive counterexamples privately.
When an oracle conflicts with a documented contract, the contract wins: adapt
the oracle rather than changing intended behavior.