Skip to content

FIELD GUIDE 001 · TYPESCRIPT + POSTGRESReal database tests. Nothing left behind.

A runnable reference for transaction rollback, typed fixtures, factories, authorization seams, and the tests that refuse to fit inside one transaction.

Trace 001One test, start to finish.
  1. 01baselinefixtures already committed
  2. 02beginone transaction for the test
  3. 03exercisereal queries + real authorization
  4. 04rollbackevery write disappears

database restored

The short version

Test the application you are actually shipping. ​

Mock the person who signed in—not the authorization decision. Read shared fixture rows through the real schema. Create the unusual state with factories. Call the same server function production calls. Then roll the whole test back.

This is deliberately a reference to copy, not a package to install. Database test infrastructure sits directly on your application's seams: its connection owner, migrations, schema types, authorization boundary, and test runner. Those seams should stay visible.

  1. 01
    A baseline worth knowing

    A few committed, label-addressed fixtures make the shared world readable without rebuilding it for every test.

  2. 02
    Variation belongs to the test

    Factories create only what the example changes. Lazy associations keep setup small without making it magical.

  3. 03
    Rollback is the cleanup

    The test runs inside an interactive transaction. A sentinel throw guarantees that a passing callback never commits.

Honest by construction

One transaction owns one connection. That makes isolation cheap. It also means concurrency is fake, database now() is frozen, and an expected SQL error can abort the transaction. The kit pins those facts with tests and gives race-sensitive work an explicit committed-mode exit.

Where it fits

Between a unit test and a full e2e. ​

These are endpoint tests: a real server function or route handler, a real schema and a real authorization decision, run in-process in milliseconds. They catch what mocks cannot (a missing tenant filter, a constraint violation, a forgotten audit write) without the browser, server and teardown cost of end-to-end tests. See where the line falls →

Choose your route

Same design. Two working implementations. ​

The root project uses Drizzle + PGlite for a zero-service first run, then exercises the same suite against Postgres. The Prisma 7 variant uses real Postgres and carries its own exact toolchain pins, fixture types, loader, and caveat tests.

For humans and agents

Read it here. Hand it to your coding agent. Own the result.

The rendered guide, raw Markdown, RECREATE.md, Agent Skill, llms.txt, and generated full-text reference all describe the same system.

Copy the agent prompt →

A reference implementation to copy from, not a dependency.