Test Suite Structure

GOVERN’s test infrastructure is organized across four layers. Each layer has a distinct purpose, execution speed, and failure signal. All layers must pass before a release gate opens.

Layer 1 — Unit Tests

Speed: Fast (< 30 seconds total) Runner: Vitest Location: Co-located with source files (foo.ts → foo.test.ts)

Unit tests cover:

• Pure functions and utilities
• Data transformation logic
• Risk scoring algorithms
• Archetype configuration validation
• Schema validation with zod
• Store logic (Zustand reducers)

Running unit tests

# From the package root
pnpm test

# From the monorepo root — all packages
pnpm -r test

# Watch mode during development
pnpm test --watch

# Coverage report
pnpm test --coverage

Key unit test files

File	What it tests
packages/core/src/archetypes/configs.test.ts	Archetype config completeness and structure
packages/core/src/formatters.test.ts	Output formatter behavior
packages/dashboard/src/stores/inner-circle-store.test.ts	Store reducers and selectors
packages/api-gateway/src/lib/monitoring-rollup.test.ts	Rollup aggregation logic
packages/api-gateway/src/lib/risk-scoring.test.ts	Risk score calculation

Unit test conventions

• Every function with branching logic has a test
• Tests use descriptive names: it('returns BLOCKED when score is below threshold')
• No mocking of internal modules — if you need to mock, the function is too coupled
• External services (Supabase, Redis, R2) are always mocked in unit tests

Layer 2 — Integration Tests

Speed: Medium (1–5 minutes) Runner: Vitest + Miniflare (Cloudflare Workers local simulator) Location: packages/<name>/src/__tests__/

Integration tests cover:

• Route handler behavior end-to-end within the API gateway
• Database query correctness against a local Supabase instance
• Durable Object state transitions
• Redis cache invalidation flows
• Supabase RLS policy enforcement

Running integration tests

# Requires local Supabase running
supabase start

# Run integration tests
pnpm test:integration

# Single package
cd packages/api-gateway && pnpm test:integration

Integration test setup

Integration tests use a dedicated test database with seeded data. The seed is reset before each test suite run:

# Reset and reseed the test database
supabase db reset --local

Key integration test areas

Area	Test location	What is verified
Monitoring pipeline	__tests__/monitoring-pipeline.test.ts	EMIT → ACCUMULATE → ROLLUP → INSCRIBE full flow
Build events	__tests__/build-events.test.ts	Event creation, skill evolution trigger, archetype scoring
Assessment API	__tests__/assessments.test.ts	Assessment CRUD, scoring, report generation
Auth middleware	__tests__/auth.test.ts	Bearer token validation, org scoping

Layer 3 — End-to-End Tests

Speed: Slow (5–15 minutes) Runner: Playwright Location: packages/<name>/e2e/

E2e tests cover:

• Critical user flows from browser to database
• Cross-component integration (dashboard calls API calls database)
• Auth flows (login, org switching, role enforcement)
• Report generation and download

Running e2e tests

# Install browsers (once)
npx playwright install

# Run e2e tests against staging
PLAYWRIGHT_BASE_URL=https://govern-staging.pages.dev pnpm test:e2e

# Run locally (requires both API and dashboard running)
pnpm dev &
PLAYWRIGHT_BASE_URL=http://localhost:4321 pnpm test:e2e

Key e2e flows

1. New org onboarding — create org → add system → run first assessment → view report
2. Assessment lifecycle — create → run probes → review results → approve/reject
3. Report export — generate PDF → verify content → download
4. Remediation flow — flag issue → create remediation → track to completion

Layer 4 — Visual Regression (Playwright Screenshots)

Speed: Medium (2–8 minutes) Runner: Playwright with toHaveScreenshot() Location: packages/<name>/e2e/visual/

See the Playwright Visual QA page for the full visual regression workflow.

Test Matrix

This matrix shows which test layers apply to each GOVERN component:

Component	Unit	Integration	E2E	Visual
API Gateway	Yes	Yes	—	—
Customer Dashboard	Yes	—	Yes	Yes
Internal Dashboard	Yes	Yes	—	Yes
Monitoring Probe	Yes	Yes	—	—
Browser Extension	Yes	—	Yes	Yes
Core Package	Yes	—	—	—
DB Package	—	Yes	—	—

Test Pass Requirements

For Gate II (V(Q)) to score >= 85%:

• Unit tests: 100% pass rate (zero failures)
• Integration tests: 100% pass rate
• E2E tests: 100% pass rate on critical path flows
• Visual regression: no unreviewed diffs

A single failing test in any layer blocks the release.

Adding New Tests

When adding a new feature:

1. Write unit tests for any function with branching logic
2. Write an integration test if the feature touches the API or database
3. Write an e2e test if the feature changes a user-visible flow
4. Add a visual snapshot if the feature changes any UI component

This is enforced by the Testing Dashboard’s coverage heatmap — new code without corresponding tests turns the heatmap red.