Testing Overview

Test framework, patterns, coverage strategy, and the three-layer quality approach -- Vitest, trovella-test-audit, and AI-assisted testing skills.

Trovella uses Vitest as its test runner across the entire monorepo. The testing strategy is built around a specific problem: AI coding agents write most tests, and AI-generated tests can achieve high coverage while verifying nothing meaningful. The solution is a three-layer approach that goes beyond coverage metrics.

Three-Layer Quality Strategy

Layer 1: Vitest with V8 Coverage

The foundation. Every package has its own vitest.config.ts with V8 coverage instrumentation. Tests run per-package through Turborepo, and CI runs only affected packages via turbo test --affected. Coverage data is output as JSON for aggregation by the CLI tool.

Layer 2: `trovella-test-audit` CLI

A custom monorepo-aware CLI tool at tools/test-audit/ that provides four commands: coverage (aggregate cross-package coverage), report (full coverage context), map (source-to-test mapping), and mutate (StrykerJS mutation testing). Mutation testing is the primary quality signal -- it proves tests actually catch bugs, not just run code. See Test Audit CLI for the full reference.

Layer 3: AI-Assisted Testing Skills

Two Claude Code skills encode TDD discipline into repeatable workflows:

/test-write -- enforces test-first development with a pre-mortem fragility catalogue and mutation verification loops
/test-review -- audits existing test quality across five dimensions (coverage, behavioral focus, completeness, isolation, mutation resilience)

These skills use the CLI tool for data-driven scoring. Quality enforcement happens during development, not after CI -- because in an agentic workflow, the agent that opened a PR has already exited by the time CI runs.

Test Categories

Category	Example	Environment	Runs In CI?
Unit tests	`@repo/ai` config, errors, chunking	`node`	Yes
Architecture fitness tests	`@repo/api` and `@repo/mcp` arch tests	`node`	Yes
RLS integration tests	`@repo/db` tenant isolation	`node` + real PostgreSQL	Yes (service container)
Component tests	`apps/web` React component tests	`jsdom`	Yes
Search tests	`@repo/search` fusion scoring	`node`	Yes

Test File Locations

Tests follow a co-located __tests__/ directory pattern within each package:

packages/ai/src/__tests__/
  config.test.ts       # Model config verification
  errors.test.ts       # Error mapping from SDK errors
  request.test.ts      # Request parameter building
  chunking.test.ts     # Text chunking logic

packages/db/src/__tests__/
  rls.test.ts          # Core RLS isolation (member table)
  rls-research.test.ts # Research table RLS isolation

packages/api/src/__tests__/
  arch.test.ts         # authorizedProcedure enforcement

packages/mcp/src/__tests__/
  arch.test.ts         # Tool registration enforcement
  auth.test.ts         # PAT token hashing
  server.test.ts       # MCP server setup
  tools.test.ts        # Tool handler tests

packages/search/src/__tests__/
  fusion.test.ts       # Reciprocal rank fusion + query classification

apps/web/src/
  app/api/admin/ai-playground/__tests__/route-helpers.test.ts
  components/admin/ai-playground/__tests__/use-playground.test.ts
  components/admin/ai-playground/__tests__/tool-use-section.test.ts

Running Tests

# Run all tests (via Turborepo)
pnpm test

# Run tests for a single package
pnpm turbo test --filter=@repo/ai

# Run with coverage
pnpm test:coverage

# Run only affected tests (CI mode)
pnpm turbo test --affected

# Run the test-audit CLI
pnpm test-audit coverage .            # Aggregate coverage
pnpm test-audit mutate packages/ai    # Mutation testing
pnpm test-audit map packages/mcp      # Source-to-test mapping

Pages in This Topic

ADR-014: Testing Infrastructure -- the decision record for Vitest, mutation testing, real PostgreSQL for RLS, and AI-assisted quality
Configuration -- per-package Vitest configs, workspace setup, and environment selection
Test Patterns -- unit, architecture fitness, RLS integration, and component test patterns with real examples
Test Audit CLI -- the trovella-test-audit tool: coverage, report, map, and mutate commands
CI Integration -- how tests run in GitHub Actions, service containers, and the --affected optimization

Cross-Domain References

Data & Storage -- Tenant Scoping -- how RLS policies are defined (the schemas that RLS tests verify)
Identity & Access -- Router Enforcement -- the architecture test pattern that enforces authorizedProcedure
Delivery -- Pipeline -- the CI pipeline where tests execute
Delivery -- Pipeline -- Quality Checks -- the specific CI step that runs pnpm turbo test --affected