db-test-kit-js
Endpoint tests that are sane to write and easy to trust
Rails made database-backed endpoint tests feel ordinary; many TypeScript stacks still do not. This runnable reference brings fast rollback isolation, readable fixtures, factories, and real authorization checks to the stacks that leave you to assemble them yourself.

- ~0.3 ms
- rollback per test
- 2
- working ORM implementations
- 1
- real authorization boundary
- 0
- packages to install from the kit
Role
Research, documentation, and engineering
Built with
- TypeScript
- Postgres
- Drizzle
- Prisma
- Vitest
The problem
Rails makes database-backed endpoint tests feel like a normal part of building an application. Across many TypeScript stacks, I could not find an equivalent system available out of the box: transaction isolation, fixtures, factories, authentication seams, and honest escape hatches working together.
Teams are often left choosing between two unsatisfying extremes: fast tests built on mocks that cannot catch a missing tenant filter or constraint violation, and full end-to-end tests with enough setup and cleanup that people avoid writing them.
The useful middle is an integration test that calls the same application function production calls, runs against a real schema and authorization decision, and leaves the database exactly as it found it.
Decisions that shaped it
- A reference, not a dependency
- Database test infrastructure touches an app's connection owner, migrations, schema types, auth boundary, and test runner. Those seams should remain visible, so the project is designed to be copied and adapted rather than installed and hidden behind a package.
- Rollback is the cleanup
- Each test runs inside an interactive transaction and throws a sentinel at the end so even a successful test rolls back. The application's database import points at that transaction, while nested application transactions become savepoints.
- Mock identity, not authorization
- Tests fake the one session lookup that says who is signed in, then exercise the real membership and tenancy checks. That makes cross-tenant access, audit writes, and missing filters observable instead of mocked away.
- Caveats belong in the suite
- One transaction means one connection: concurrent queries serialize, database now() is frozen, and a failed statement aborts the transaction. The kit pins those facts with tests and gives race-sensitive cases an explicit committed-mode escape hatch.
What's inside
- Rollback harness
- A Vitest setup that wraps each example in a transaction and proves writes disappear before the next test.
- Readable fixtures
- A small committed baseline keyed by labels, with deterministic IDs and type-checked references between rows.
- Factories for variation
- Fishery factories persist only the state a test changes, with lazy associations that keep setup compact.
- Seam and caveat tests
- Guardrails catch extra database connections and document the transaction behaviors that can otherwise make a suite quietly dishonest.
- Two adoption paths
- The root project demonstrates Drizzle with PGlite or Postgres; a complete Prisma 7 variant covers the ORM-specific differences against real Postgres.
- Docs for humans and agents
- A rendered field guide, raw Markdown, RECREATE.md, an Agent Skill, llms.txt, and a generated full-text reference all teach the same pattern.
Under the hood
The example domain is a small multi-tenant app with organizations, members, projects, tasks, and an audit log. Tests go through real server functions and the real membership boundary, so the examples demonstrate behavior that mocks routinely miss.
The fast path runs in-process on PGlite with no database service. The same suite can run against Postgres, and concurrency tests intentionally leave the wrapping transaction for a throwaway committed-mode database. The Prisma variant carries the same design with its own verified harness and toolchain pins.
Use it
Choose the Drizzle or Prisma path, read the compatibility checklist, and copy only the layers your repository is missing. The guide ends with adversarial checks: deliberately fail inside the transaction, prove the seam guard catches a second pool, and verify existing tests still mean what they meant before.
The repository is MIT licensed. Take the files, adapt them to the application in front of you, and keep the database boundary understandable.
