Testing

TDD is Non-Negotiable

Matrix OS follows strict Test-Driven Development. Every feature starts with a failing test:

1. Red -- write a failing test that describes the desired behavior
2. Green -- write the minimum code to make it pass
3. Refactor -- clean up while keeping tests green

Coverage Target

99-100% across kernel and gateway packages. Test counts and runtime change as the suite grows; use the current test report rather than a fixed historical estimate.

Running Tests

bun run test              # Unit tests
bun run test:watch        # Watch mode for development
bun run test:coverage     # Generate coverage report
bun run test:integration  # Integration tests (needs ANTHROPIC_API_KEY)

Engineering handbook

For CI timing metrics, profiling, shard balancing, database fixtures, and dedicated-runner benchmarks, see the engineering handbook.

Test Structure

Tests live in tests/ at the project root, organized by package:

tests/
  kernel/             # Kernel unit tests
    spawn.test.ts     # spawnKernel() tests
    options.test.ts   # kernelOptions() tests
    prompt.test.ts    # buildSystemPrompt() tests
    ipc-server.test.ts # IPC tool tests
    agents.test.ts    # Agent loading and parsing tests
    hooks.test.ts     # Hook behavior tests
    soul.test.ts      # SOUL identity tests
  gateway/            # Gateway unit tests
    dispatcher.test.ts # Dispatch queue tests
    watcher.test.ts   # File watcher tests
    channels/         # Channel adapter tests
    cron.test.ts      # Cron service tests
    heartbeat.test.ts # Heartbeat tests
  shell/              # Shell component tests
  integration/        # Integration tests (real API calls)
  e2e/                # End-to-end tests

Test Categories

Unit Tests

Pure function tests with mocked dependencies. Use vi.mock() for external services. One test file per source module.

Integration Tests

Make real API calls to Claude. Requirements:

• ANTHROPIC_API_KEY environment variable set
• Uses Claude Haiku model to keep costs under $0.10 per run
• Run separately: bun run test:integration

Contract Tests

Verify IPC tool schemas match their implementations. Ensure Zod schemas correctly validate inputs and tools return expected shapes.

E2E Tests

Full system tests cover the complete flow from user input through the gateway to kernel response. Run them with bun run test:e2e; browser and Electron prerequisites depend on the selected suite.

Spike Before Spec

For undocumented SDK behavior, write a throwaway spike test against the real SDK before committing to an approach. Spike files go in spike/ and are excluded from the main test suite. This prevents building on unverified assumptions.

Writing Tests

Conventions:

• Descriptive describe blocks matching module structure
• Test names describe the expected behavior, not the implementation
• Use vi.mock() for external dependencies (API calls, file system)
• Keep tests focused -- one assertion per it block when practical
• Integration tests are clearly separated and use Claude Haiku