Testing

Testing

AgentCTX uses Vitest for testing. Every module under src/{name}/ must have corresponding tests in tests/{name}/.

Running Tests

# Run all tests
npx vitest run

# Run a specific module's tests
npx vitest run tests/ctx/
npx vitest run tests/gateway/
npx vitest run tests/sidecar/

# Watch mode
npx vitest watch

# With coverage
npx vitest run --coverage

Test Structure

Tests mirror the src/ structure:

tests/
├── ctx/
│   ├── parser.test.ts       75 test cases for the CTX parser
│   ├── normalizer.test.ts   Unicode normalization tests
│   ├── serializer.test.ts   AST serialization tests
│   └── splitter.test.ts     Multi-statement splitting tests
├── gateway/
│   ├── gateway.test.ts      Pipeline and routing tests
│   ├── pipeline.test.ts     Middleware composition tests
│   └── registry.test.ts     Backend registry tests
├── sidecar/
│   ├── sidecar.test.ts      Translation tests
│   └── emitters.test.ts     Emitter backend tests
├── storage/
│   ├── objects.test.ts      CAS object store tests
│   └── refs.test.ts         Reference store tests
├── crypto/
│   └── crypto.test.ts       Ed25519 signing/verification tests
└── ...

Writing Tests

Agent-Centric Assertions (R6)

Tests must assert on structured fields, not string matching:

// ❌ Human-centric test
expect(result).toContain("Found 3 results");

// ✅ Agent-centric test
expect(result.ok).toBe(true);
expect(result.count).toBe(3);
expect(result.results[0].score).toBeGreaterThan(0.9);

Error Code Testing (R2)

Test error codes, not error messages:

// ❌
expect(() => parser.parse("xyz")).toThrow("invalid operator");

// ✅
try {
  parser.parse("xyz");
} catch (e) {
  expect(e.data.code).toBe("INVALID_OPERATOR");
  expect(e.data.position).toBe(0);
}

Mocking Dependencies

Mock external dependencies (SurrealDB, filesystem, HTTP):

import { vi } from 'vitest';

const mockQuery = vi.fn().mockResolvedValue([{ id: 'x', data: '...' }]);
const store = new MemoryManager(mockObjects, mockRefs);

Coverage Requirements

• Every modified module must have a corresponding tests/{module}/*.test.ts
• Phase gates cannot pass without test coverage verification
• The CTX parser alone has 75 test cases covering all operators, planes, verbs, filters, decorators, and error cases

See Also

• Architecture Guide — module structure
• Formal Specification — parser test coverage