typescript-test-writing

Writing TypeScript Tests in llxprt-code

Distilled from dev-docs/RULES.md. When in doubt, read RULES.md in full — it is the source of truth for development guidelines.

Core principle: TDD is mandatory

Every line of production code must be written in response to a failing test. No exceptions.

Red-Green-Refactor, followed strictly:

1. RED: Write a failing test for the next small behavior.
2. GREEN: Write ONLY enough code to make the test pass.
3. REFACTOR: Only if it improves clarity.
4. COMMIT: Feature + tests together; refactoring separately.

Stack rules (non-negotiable)

• Bun + bun:test ONLY. Never create Vitest or Node test suites, and never add new .js files — everything is TypeScript run with bun.

• TypeScript strict mode: no any (use unknown with type guards), no type assertions (use type predicates), explicit return types.

• Import pattern (bun:test re-exports vi, mock, and Mock):

  import {
    describe,
    it,
    expect,
    beforeEach,
    afterEach,
    vi,
    type Mock,
  } from 'bun:test';
  

• Prefer immutable data in tests and fixtures ({ ...cart, items: [...cart.items, item] }); never mutate shared fixtures between tests.

Test behavior, not implementation

✅ Test:

• Public API behavior
• Input → Output transformations
• Edge cases and error conditions
• Integration between units
• Schema validation

❌ Never test:

• Implementation details
• Private methods
• Third-party libraries
• Mock interactions

❌ Never enshrine bugs as specification: do not write a passing test that asserts incorrect behavior, even if that is what the code currently does. If you discover a bug while writing tests: (1) file an issue or ask the user, (2) write a failing test that asserts the CORRECT behavior, (3) fix the production code so the test passes. A suite that encodes bugs as passing tests is worse than no tests — it actively prevents future fixes.

Test structure

• describe: feature/component name.
• it: specific behavior in plain English.
• Arrange-Act-Assert: clear sections; one behavior per test.
• DRY setup: never copy-paste identical beforeEach/afterEach boilerplate (e.g. temp-dir creation, cleanup) across describe blocks. Extract a shared helper that wires the lifecycle hooks (e.g. a useTempDir() helper that registers beforeEach/afterEach internally and returns a lazy accessor). Repeating 5+ lines of identical setup in N describe blocks is a maintenance hazard; one line of shared setup per describe block is the target.