yellowjacket/.planning/milestones/v1.0-phases/03-test-infrastructure/03-CONTEXT.md

Phase 3: Test Infrastructure - Context

Gathered: 2026-03-02 Status: Ready for planning

## Phase Boundary

Create database.NewTestDB(t) — an in-memory SQLite test helper that mirrors production setup (migrations + PRAGMAs) — and apply production SQLite PRAGMAs (synchronous=NORMAL, cache_size=-8000, mmap_size=67108864) to the real NewDB(). This phase delivers the test foundation; actual test writing happens in Phases 4-5.

## Implementation Decisions

Test Helper API Shape

• NewTestDB(t *testing.T) returns *DB only — no cleanup function, no error return
• Cleanup registered internally via t.Cleanup() — callers just use the DB and forget
• No functional options — every test DB gets the full production-mirror setup (PRAGMAs + all migrations)
• Does NOT expose raw *sql.DB — tests use DB.ExecContext() / DB.Queries like production code
• Lives in database/testhelper.go (exported, importable by other packages)

PRAGMA Behavior

• All PRAGMAs applied identically in tests and production — even mmap_size on :memory: (verifies code path, true mirror)
• Shared applyPRAGMAs(*sql.DB) internal function called by both NewDB() and NewTestDB() — single source of truth
• Test DBs use the same connection string params as production (?_busy_timeout=5000&_journal_mode=WAL)
• PRAGMAs applied before schema creation — tuning first, then DDL/DML

Test Helper Scope

• No test data seeding helpers in Phase 3 — Phases 4-5 create fixtures as needed
• Future test phases should use sqlcgen.Queries (not raw SQL) for inserting test data — same path as production
• Skip the orphan cleanup query in NewTestDB — test DBs start empty, no orphans to clean
• No health check (SELECT 1) — trust that successful Open + PRAGMAs + migrations means the DB is usable

Claude's Discretion

• Internal helper function naming (applyPRAGMAs vs configurePRAGMAs vs similar)
• Whether NewTestDB calls t.Fatal() or t.Helper() + t.Fatal() on setup failure
• Exact error wrapping style in the shared PRAGMA function

## Specific Ideas

• The shared applyPRAGMAs function is the key architectural piece — it prevents production and test PRAGMA sets from drifting apart
• NewTestDB should mirror the NewDB code path as closely as possible, minus the file-path resolution and orphan cleanup
• Connection string for test: ":memory:?_busy_timeout=5000&_journal_mode=WAL" (same params, in-memory URI)

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 03-test-infrastructure Context gathered: 2026-03-02