New guide at docs/references/testing/database-testing.md describing:
- When to use setupTestDatabase() (and when not to).
- Options, lifecycle behaviour, and PRAGMA handling.
- Migration recipe (before/after diffs) for converting legacy tests.
- Anti-patterns: vi.mock('@application') override, hand-written
CREATE TABLE SQL, describe.concurrent within harness scope,
nested setupTestDatabase() calls, re-adding the
vi.mock('node:fs', importOriginal) escape hatch.
- Gotchas: LibSQL transaction connection recycle + setPragma replay,
pathToFileURL for Windows, FTS5 with NULL content, truncate-vs-drop.
Linked from CLAUDE.md's Testing Guidelines section so future
contributors find the convention.
