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

• Use bun:test for 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.
• Describe by behaviour, not by function name
• Avoid hidden shared mutable state. Prefer per-test setup; use beforeEach only for deterministic reset, and use expensive shared fixtures only when explicit and isolated
• Prefer plain fakes over mocking libraries for simple cases; use mocks when simulating failure modes, testing varied edge-case inputs, or isolating external services
• Test tenant isolation and ownership-source rules at the highest meaningful layer, not only as pure helper tests
• 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
• 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
• Avoid "tests for tests' sake": don't add shallow examples just to increase coverage if a stronger invariant test would cover the same surface with more signal
• Run tests through the owning package script so preloads and setup survive: bun run test -- --bail -t "<name>". Do not call a raw runner from the worktree root when the package script supplies configuration.
• 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.
• 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.
• Keep time, randomness, network, filesystem, and database ownership explicit in tests. Pin or inject them rather than relying on ambient machine state.