Case studyLiveMIT licensed

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.

db-test-kit-js code editor, passing test results, and database rollback
~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.