testing-conventions

Testing Conventions

Feature Changes Must Be Verified (Most Important Rule)

Any substantive change to source files under src/ must:

1. Add dedicated tests for the new functionality — passing existing tests is not enough. Each new feature/field/parameter needs corresponding test cases; these must fail when the feature is removed.
2. Evaluate whether e2e tests need updates — if the change affects interaction with the real Agent (e.g. params, output parsing, event types), add new assertions in e2e.
3. Run e2e once (pnpm run e2e) to ensure real scenarios still work — even if the change seems small.

⚠️ Anti-Pattern Warning

"Changed code + all old tests pass = done" — that is wrong. Old tests only verify old behavior. New functionality without dedicated tests is effectively unverified.

Typical mistakes:

• Added apiKey to InvokeOpts → but no test verifies apiKey is actually passed to the engine
• Added durationMs to done event → but no test for with/without duration_ms scenarios
• Modified parseStreamLine → but e2e has no assertion for the new fields returned by the real Agent

Correct approach:

1. Unit tests: mock engine captures new params; verify end-to-end propagation of new fields from source to consumer
2. e2e assertions: verify new fields have values in real conversations (e.g. durationMs > 0)
3. Do not consider it done until tests have been run

Unit Tests (vitest)

Location: src/__tests__/<module>.test.ts

Mock Engine Pattern

Unit tests do not call the real Agent (Cursor / Claude Code). Replace with a mock engine:

async function* mockInvoke(prompt, opts): AsyncIterable<StreamEvent> {
  yield { type: 'text', content: 'mock response' };
  yield { type: 'done', sessionId: 'mock-session-123' };
}

Inject via vi.mock('../engine.js', ...), returning mock engine from createEngine.

Key Test Scenarios

• session.test.ts: Multi-key routing, Phase 1 format migration, concurrency safety
• index.test.ts: sessionKey routing, KeyedMutex concurrency isolation, resetSession
• server.test.ts: All HTTP endpoints, SSE streaming, Bearer auth, CORS, input validation
• engine.test.ts: stream-json parsing (parseStreamLine + parseClaudeStreamLine), ANSI stripping, injectClaudeSkills, createEngine factory
• workspace.test.ts: golem.yaml read/write, skills scanning, AGENTS.md generation