caliber-testing

Caliber Testing

Critical

• All test files MUST be placed in __tests__/ directories parallel to source files: src/[module]/__tests__/[module].test.ts
• Register any new __tests__/ directories in vitest.config.ts's include glob (already configured: src/**/*.test.ts)
• NEVER mock src/test/setup.ts — it is the global LLM provider mock already applied to all tests
• Environment variable tests MUST save process.env in beforeEach, restore in afterEach, and explicitly delete env vars to test absence
• Temporary file/directory cleanup MUST happen in afterEach, not in individual test cleanup. Use fs.rmSync(dir, { recursive: true, force: true })
• When a test requires unmocking modules mocked in global setup, call vi.unmock('../module.js') BEFORE the import statement
• Run pnpm test locally and pnpm test:coverage before committing to verify coverage thresholds (lines: 50, functions: 50, branches: 50, statements: 50)

Instructions

Step 1: Create the test file in the correct directory

Create src/[module]/__tests__/[module].test.ts. The parent source file is src/[module]/[module].ts.

Verify: The __tests__ directory exists at the same level as the source file being tested.

Step 2: Import test framework

At the top of every test file, import from vitest:

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';

Add additional imports based on what you're testing:

• File system: import fs from 'fs'; import path from 'path'; import os from 'os';
• Temporary files: Use fs.mkdtempSync(path.join(os.tmpdir(), 'caliber-prefix-'))
• Exec: import { execSync } from 'child_process';

Verify: All required test utilities are imported before test definitions.

Step 3: Set up module mocking (if needed)

If testing a module that imports other modules you want to mock:

vi.mock('../config.js', () => ({
  loadConfig: vi.fn(),
  writeConfigFile: vi.fn(),
}));

For complex mocks with test-time factory functions (hoisted):

const { mockLoadConfig } = vi.hoisted(() => ({
  mockLoadConfig: vi.fn(),
}));

vi.mock('../config.js', () => ({
  loadConfig: () => mockLoadConfig(),
}));