# db-test-kit-js — complete documentation for language models Generated from the same Markdown that builds the documentation site. Prefer RECREATE.md when performing an adoption or update because it is the canonical operational checklist. --- # Home

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 →

--- # Quick start # Quick start The repository contains two small multi-tenant applications with the same tests. The default project uses Drizzle and starts with PGlite, so it needs no database service. The Prisma project uses disposable Postgres. ## Drizzle with zero setup ```bash git clone https://github.com/danielrose7/db-test-kit-js.git cd db-test-kit-js corepack enable pnpm install --frozen-lockfile pnpm typecheck pnpm test ``` The suite proves fixture loading, rollback isolation, a tenancy matrix, factories, savepoints, transaction failure behavior, and the database seam. The concurrency test is skipped because PGlite's single session cannot demonstrate a real race. ## Drizzle against Postgres ```bash docker compose up -d pnpm test:pg ``` This runs the same suite plus `test/tasks.concurrency.test.ts` against a throwaway database. ## Prisma 7 against Postgres ```bash cd variants/prisma pnpm install --frozen-lockfile pnpm typecheck pnpm test ``` The Prisma variant uses its own exact ORM/toolchain pins and lockfile. Its test script generates the client, deploys migrations, loads the baseline, and runs the suite. ::: warning Use only a disposable test database Committed-mode tests and fixture bootstrap mutate data outside the per-test rollback transaction. Never point either project at development, staging, or production. Read [Database safety](/reference/safety) before adapting the Postgres scripts. ::: ## Next - [See how the transaction, fixtures, and factories fit together](/guide/how-it-works) - [Choose an adoption path](/guide/choose-a-path) - [Give the canonical checklist to an agent](/agents/) --- # How it works # How it works The kit combines three familiar testing tools and one application seam. None is novel alone; their composition is the useful part. For the longer history—including the Rails APIs that directly inspired the fixture model—see [Design lineage](/reference/lineage/). To begin from working tests instead, browse the [example walkthroughs](/examples/). ## 1. Rollback isolation Vitest's `aroundEach` opens an interactive transaction, makes its client current, runs the test, and throws a private sentinel error. Throwing matters: a transaction callback that returns normally commits. The outer harness recognizes only its own sentinel and lets every other failure reach Vitest. Production code continues importing the normal application `db`. In singleton-style applications, the test setup mocks that one module with a proxy to the current transaction. Access outside a test transaction throws unless the file explicitly selected committed mode. ## 2. A committed fixture baseline Fixtures represent the handful of records almost every test can safely read: two tenants, membership edges, users with different authorization states, and a few domain records. They load once before the suite, not before each test. Rows are keyed by labels. IDs are UUIDv5 values derived from the fixture set and label, so relationships can be declared without querying: ```ts organizationId: idOf(organizationFixtures, "acme") ``` The label is checked by TypeScript. A misspelling fails typechecking instead of becoming a missing row at runtime. ## 3. Factories for variation Factories create state owned by one test. Persistence happens in Fishery's `onCreate`, leaving `build()` pure. Associations are lazy: a task factory can create its organization and project only when the test did not provide them. The rule of thumb is simple: | Data | Use | |---|---| | Read by many tests and rarely changed | Fixture | | Meaningful only inside one test | Factory | | A repeated graph or workflow state | Scenario composed from factories | ## 4. A real authorization boundary The session lookup is fakeable; the tenant or membership check is not. Tests can say `signInAs(user)` and then call the real server function. The database-backed authorization query, domain query, mutation, and audit write all happen inside the same rollback transaction. ## 5. An explicit escape hatch One transaction owns one connection. That is desirable isolation, but it cannot prove behavior that requires independent transactions. A committed-mode file opts out, creates its own tenant, and runs only against disposable Postgres. This makes the limitation visible rather than silently weakening a race test. See [Caveats and escape hatches](/reference/caveats) for the executable boundaries. --- # Where this fits: endpoint tests # Where this fits: endpoint tests Most projects have two ends of the testing spectrum and a gap in the middle. | | Unit tests | **Endpoint tests (this kit)** | Full e2e | |---|---|---|---| | Entry point | A function with its collaborators mocked | A server function, Server Action or route handler, called in-process | A browser or HTTP client against a running deployment | | Database | Mocked or absent | Real Postgres engine, real schema, real constraints | Real, shared, usually reset between runs | | Authorization | Stubbed | Real decision, fake identity | Real login flow | | Speed | Milliseconds | Low milliseconds per test | Seconds, plus a server to boot | | Isolation | Trivial | Transaction rollback | Teardown scripts, unique data, or serial runs | | Typical failure it catches | Logic bugs | Wrong query, missing tenant filter, constraint violation, missing audit write | Broken wiring, UI regressions, deployment config | The middle column is what the kit is built for. A mock cannot tell you that your `WHERE` clause forgot `organization_id`; a browser test can, but it takes seconds, needs a running server, and is awkward to run dozens of times for every role and tenant combination. An endpoint test runs the real handler against the real schema, many times, cheaply. ## What counts as an endpoint here Anything that is the application's public entry into the data layer: - a `"use server"` function or Server Action; - a Next.js, Hono or Fetch-style route handler; - a tRPC procedure or service-layer function that your controllers all delegate to. The example app's `listProjects`, `getProject` and `createProject` are this shape. Each calls `requireMembership`, runs a tenant-scoped query and writes an audit event. The tests call them directly, so the tests exercise the same code a request would reach. ## Why the rollback pattern suits it Endpoint tests tend to be many, and each needs a believable world: two tenants, a member and a non-member, a record owned by someone else. That is the fixture-plus-factory baseline. Each test then makes one request-shaped call and asserts on the result and on the rows left behind. Because the whole test, including any writes the handler made, rolls back, tests don't interfere and need no cleanup, which keeps them cheap enough to write the unglamorous cases: signed out, wrong tenant, malformed input, duplicate submit. ```ts it("does not return another tenant's project", async () => { signInAs(fx.users.olivia); // fake identity only const result = await getProject(fx.organizations.acme.id, fx.projects.secret.id); expect(result).toBeNull(); // real membership + real WHERE clause }); ``` ## Calling a route handler If your endpoints are HTTP handlers, call them in-process rather than starting a server. Fetch-style handlers take a `Request` and return a `Response`, so no socket is involved: ```ts // Illustrative: the example app has server functions rather than HTTP routes. import { POST } from "@/app/api/projects/route"; it("creates a project and audits it", async () => { signInAs(fx.users.olivia); const res = await POST( new Request("http://test/api/projects", { method: "POST", body: JSON.stringify({ organizationId: fx.organizations.acme.id, name: "Launch" }), }), ); expect(res.status).toBe(201); const rows = await testDb.select().from(auditLogs).where(eq(auditLogs.action, "create")); expect(rows).toHaveLength(1); }); ``` Frameworks that expose an in-process client work the same way, for example Hono's `app.request()`. The essential property is that the handler runs in the test's own process, so it imports the mocked `db` and joins the test's transaction. Because the session lookup is the only faked piece, there are no cookies or tokens to forge. Status codes, validation errors and the shape of the response body are all real. ## Where to stop The boundary is the transaction. These stay outside it, and belong to a different kind of test: - **A separately running server.** Supertest against a spawned process, or a browser against a dev server, uses its own connections and cannot see your uncommitted rows. That is end-to-end territory, and it needs committed data and its own cleanup. - **The real login flow.** The kit fakes the session lookup. Cookie handling, OAuth callbacks and session expiry need an e2e or a dedicated auth test. - **Middleware and routing.** Calling a handler directly skips whatever runs before it, such as redirects, rewrites and edge middleware. - **Genuine concurrency.** Opt the file into committed mode; see [Real concurrency](/examples/concurrency). - **Rendering.** Nothing here checks that a page displays the data. A healthy suite usually has all three layers: many unit tests, a broad endpoint layer built on this kit, and a handful of e2e journeys that prove the pieces are wired together. The endpoint layer is where the bulk of tenant-isolation, permission and data-integrity coverage tends to land. ## Related - [How it works](/guide/how-it-works) - [Authorization and tenancy](/examples/authorization): one matrix across several boundaries. - [Caveats and escape hatches](/reference/caveats) --- # Choose an adoption path # Choose an adoption path Start with two questions: which ORM owns your transaction client, and how does application code obtain that client? | ORM | Application database access | Starting point | |---|---|---| | Drizzle | One imported singleton | Root project; mock the seam module | | Drizzle | Dependency injection | Root project; pass `tx` and skip the module mock | | Prisma 7 | One imported singleton | `variants/prisma`; mock the seam module | | Prisma 7 | Dependency injection | `variants/prisma`; pass the interactive client | ## Use the Drizzle path when - production uses Drizzle with Postgres; - tests can use `node-postgres`, `postgres-js`, or PGlite for interactive transactions; - the test process can run the project's migrations. [Adopt the Drizzle version →](/guide/drizzle) ## Use the Prisma path when - the project uses Prisma 7 with Postgres; - a real disposable Postgres database is available; - the generated client can be produced before tests. [Adopt the Prisma version →](/guide/prisma) ## Stop before copying when - the target does not use Postgres; - database clients are constructed throughout the application instead of behind one seam; - tests cannot open interactive transactions; - an existing harness already solves rollback isolation and only fixtures or guard tests are missing. In the last case, preserve the working harness and add only the missing layers. `RECREATE.md` begins with this reconnaissance deliberately. --- # Adopt the Drizzle version # Adopt the Drizzle version The root project is the canonical Drizzle implementation. Do not copy its example domain wholesale. Use the classifications in `RECREATE.md`. ## What normally transfers unchanged - fixture identity and label helpers; - fixed fixture clock; - global setup shape; - rollback sentinel behavior; - the test that forbids database access outside a transaction. ## What must match the target - schema and database module imports; - migration runner and migrations directory; - session lookup module; - seam-guard allow-list; - fixture rows and dependency order; - factories and authorization tests; - test database name, URL, and safety rules. ## Driver boundary Production may use Neon's HTTP driver while tests use `node-postgres` or PGlite. The requirement is not that production and tests share a transport; it is that application queries share the same Drizzle schema and the test driver supports an interactive transaction held open across a test. ## Canonical procedure Read the complete [`RECREATE.md`](https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md) before editing a target repository. It includes reconnaissance, the file map, verification failures to induce deliberately, and pitfalls discovered during cold adoption trials. --- # Adopt the Prisma version # Adopt the Prisma version `variants/prisma/` is a complete Prisma 7 project, not a sketch layered over the Drizzle source. Start there because the ORM differences affect the harness, fixture types, loader, bootstrap, generated code, and database requirements. ## Important differences - Prisma requires real Postgres in this reference; there is no PGlite default. - The interactive transaction uses explicit `timeout` and `maxWait` values. - Fixture sets name Prisma delegates and use scalar foreign-key fields. - Bootstrap runs `prisma generate` and `prisma migrate deploy`. - Fixture loading uses a plain, unextended client so application extensions cannot reject cleanup. - Prisma `@default(now())` behavior differs from SQL `DEFAULT now()`; both behaviors are pinned by tests. ## Version policy The Prisma CLI, client, and adapter are pinned to exactly the same current stable Prisma 7 release. The variant does not claim Prisma 8 compatibility: that major version changes core APIs and deserves a separate implementation and test pass, not a widened version range. ## Dependency-injected applications If application functions already accept a Prisma client, skip `vi.mock`. Pass the current transaction client to the real functions and keep authorization dependencies real except for the session identity. Read the [variant README](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/README.md) and then follow the Prisma section of `RECREATE.md`. --- # Update an existing copy # Update an existing copy Copied infrastructure needs a visible provenance trail. Every managed COPY or ADAPT file begins with a header such as: ```ts // db-test-kit-js v0.2 · ADAPT — copied; adapt only where RECREATE.md says ``` ## The update loop 1. Read the copied files' headers. A missing header means the copy predates v0.2. 2. Read every newer entry in `CHANGELOG.md`. 3. Replace changed COPY files from the reference. 4. Apply changed ADAPT files as a three-way comparison, preserving the target's imports and seams. 5. Never overwrite EXAMPLE fixtures, factories, or domain tests. 6. Stamp touched files with the new version. A headerless v0.1→v0.2 update stamps every managed file. 7. Repeat the complete verification checklist, including deliberate failure checks. The update procedure was tested on a reconstructed v0.1 copy. That trial found the header migration and typecheck-command ambiguities now documented in the canonical instructions. For operational details, use [`RECREATE.md`](https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md), not this overview. --- # Examples # Examples Start with behavior, then follow the code into the repository. Each example shows the smallest useful excerpt from both implementations when the ORM changes the expression of the pattern. | Example | What it demonstrates | Start here | |---|---|---| | Ordinary rollback test | A write is visible now and absent in the next test | [Read the example](/examples/rollback-test) | | Fixtures + factories | Shared identities plus variation owned by one test | [Read the example](/examples/fixtures-factories) | | Authorization + tenancy | Fake identity; keep the database authorization decision real | [Read the example](/examples/authorization) | | Real concurrency | Leave the wrapper transaction when separate connections are the behavior | [Read the example](/examples/concurrency) | These examples call endpoints in-process; see [where that sits between unit and e2e tests](/guide/endpoint-testing). ## The recurring shape ```ts it("exercises the real application", async () => { signInAs(fx.users.olivia); // replace identity lookup const record = await domainFactory.create(); // arrange test-owned variation const result = await serverFunction(record); // real auth + real queries expect(result).toEqual(expected); // rollback follows automatically }); ``` There is no cleanup call in an ordinary test. Vitest's `aroundEach` owns the transaction, the application database import points at that transaction, and the harness forces a rollback after the assertion. ## Browse the complete implementations - [Drizzle root project](https://github.com/danielrose7/db-test-kit-js/tree/main/test) - [Prisma 7 variant](https://github.com/danielrose7/db-test-kit-js/tree/main/variants/prisma/test) - [Application code under test](https://github.com/danielrose7/db-test-kit-js/tree/main/src) The excerpts explain the design; the repository tests are the executable authority. --- # Example: a rollback test # A normal rollback test The most important example is intentionally uneventful: write through the real application database, assert the state, and omit cleanup. ```ts{2-3} it("a test's writes are visible to it...", async () => { await db.update(users).set({ name: "Changed" }).where(eq(users.id, fx.users.olivia.id)); await userFactory.create({ name: "RolledBack" }); const [olivia] = await db.select().from(users).where(eq(users.id, fx.users.olivia.id)); expect(olivia.name).toBe("Changed"); }); ``` The next test sees the committed baseline again: ```ts{2,4} it("...and gone in the next test", async () => { const [olivia] = await db.select().from(users).where(eq(users.id, fx.users.olivia.id)); expect(olivia.name).toBe("Olivia Owner"); expect(await db.select().from(users).where(eq(users.name, "RolledBack"))).toHaveLength(0); }); ``` The test did not reset the user or delete the factory record. The surrounding transaction was discarded. ## What wraps the test ```ts{1,3} aroundEach(async (runTest) => { try { await inRolledBackTransaction(runTest); } finally { signOut(); } }); ``` Inside the harness, a private error forces rollback because an interactive transaction callback that returns normally would commit: ```ts{7} await committedDb().transaction(async (tx) => { current = tx as unknown as TestDatabase; try { await runTest(); } finally { current = undefined; } throw new Rollback(); }); ``` ## Full source - [Drizzle fixture and rollback tests](https://github.com/danielrose7/db-test-kit-js/blob/main/test/fixtures.test.ts) - [Drizzle transaction setup](https://github.com/danielrose7/db-test-kit-js/blob/main/test/db/setup.ts) - [Drizzle harness](https://github.com/danielrose7/db-test-kit-js/blob/main/test/db/harness.ts) - [Prisma fixture and rollback tests](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/test/fixtures.test.ts) - [Prisma harness](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/test/db/harness.ts) --- # Example: fixtures and factories # Fixtures and factories together Fixtures answer “which known actor or tenant?” Factories answer “what unusual state does this test own?” A test can use both without rebuilding the shared world. ```ts{3,6} it("creates a project for a member created by a factory", async () => { // A new tenant and user belong only to this test. const membership = await memberFactory.owner().create(); signInAs(membership.user); const id = await createProject(membership.organizationId, "Fresh"); expect((await listProjects(membership.organizationId)).map((p) => p.id)).toEqual([id]); }); ``` For a shared relationship, pass a fixture ID into the factory instead of creating another tenant: ```ts{2} const task = await taskFactory.create({ organizationId: fx.organizations.acme.id, title: "Review the release", }); ``` The label `acme` carries meaning across tests. The task does not; it rolls back with this test. ## A readable fixture relationship ```ts{3} export const projectFixtures = fixtures(projects, "projects", { website: { organizationId: idOf(organizationFixtures, "acme"), name: "Website", createdAt: FIXTURE_EPOCH, }, }); ``` `idOf()` checks the label at compile time and computes the ID without first querying the database. ## Full source - [Drizzle project tests](https://github.com/danielrose7/db-test-kit-js/blob/main/test/projects.test.ts) - [Drizzle fixtures](https://github.com/danielrose7/db-test-kit-js/tree/main/test/fixtures) - [Drizzle factories](https://github.com/danielrose7/db-test-kit-js/tree/main/test/factories) - [Prisma project tests](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/test/projects.test.ts) - [Prisma fixtures](https://github.com/danielrose7/db-test-kit-js/tree/main/variants/prisma/test/fixtures) - [Prisma factories](https://github.com/danielrose7/db-test-kit-js/tree/main/variants/prisma/test/factories) For the design rules behind these choices, see [Fixtures](/reference/fixtures) and [Factories](/reference/factories). --- # Example: authorization and tenancy # Authorization and tenancy The session lookup is a controlled test seam. The membership query, tenant filter, domain query, and audit write remain real. ## One matrix, several boundaries ```ts it("rejects a signed-out caller", async () => { await expect(listProjects(fx.organizations.acme.id)).rejects.toThrow("Not authenticated"); }); it("rejects a signed-in user who isn't a member", async () => { signInAs(fx.users.ned); await expect(listProjects(fx.organizations.acme.id)).rejects.toThrow("Not a member"); }); it("doesn't leak another org's project", async () => { signInAs(fx.users.olivia); expect(await getProject(fx.organizations.acme.id, fx.projects.secret.id)).toBeNull(); await expect(listProjects(fx.organizations.other.id)).rejects.toThrow("Not a member"); }); ``` These are application tests, not controller mocks. They call the same functions production calls against the real schema. ## ORM-specific assertion, same behavior ::: code-group ```ts [Drizzle] const logs = await db .select() .from(auditLogs) .where(eq(auditLogs.resourceId, fx.projects.website.id)); expect(logs[0]).toMatchObject({ actorUserId: fx.users.olivia.id, action: "view" }); ``` ```ts [Prisma] const logs = await prisma.auditLog.findMany({ where: { resourceId: fx.projects.website.id }, }); expect(logs[0]).toMatchObject({ actorUserId: fx.users.olivia.id, action: "view" }); ``` ::: The assertion changes with the client API. The authorization boundary does not. ## Full source - [Drizzle tenancy suite](https://github.com/danielrose7/db-test-kit-js/blob/main/test/projects.test.ts) - [Prisma tenancy suite](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/test/projects.test.ts) - [Application membership boundary](https://github.com/danielrose7/db-test-kit-js/blob/main/src/membership.ts) - [Test session seam](https://github.com/danielrose7/db-test-kit-js/blob/main/test/auth/session.ts) --- # Example: real concurrency # Real concurrency One rollback transaction owns one connection. That is excellent isolation, but simultaneous promises on that client do not demonstrate independent transactions racing. A concurrency test opts out explicitly. ```ts{1,7-12} useCommittedDb(); it("exactly one of several simultaneous claims wins", async () => { const task = await taskFactory.create(); const members = await Promise.all( [1, 2, 3, 4].map(() => memberFactory.create({ organizationId: task.organizationId })), ); const results = await Promise.all( members.map(async (membership) => { signInAs(membership.user); return claimTask(task.organizationId, task.id); }), ); expect(results.filter(Boolean)).toHaveLength(1); }); ``` `useCommittedDb()` is file-scoped. Factories now commit, so this suite creates an isolated tenant rather than changing shared fixture rows. The Drizzle root skips the test unless it is running against real Postgres; the in-process PGlite path has only one session. ## Why this is separate ```ts describe.skipIf(!usingRealPostgres)("claimTask (concurrent)", () => { // independent application calls can now use independent pool connections }); ``` This is not a slower version of every test. It is a targeted escape hatch for behavior whose subject is commit visibility, locks, or races. ## Full source - [Drizzle concurrency test](https://github.com/danielrose7/db-test-kit-js/blob/main/test/tasks.concurrency.test.ts) - [Prisma concurrency test](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/test/tasks.concurrency.test.ts) - [Drizzle claim implementation](https://github.com/danielrose7/db-test-kit-js/blob/main/src/tasks.ts) - [Prisma claim implementation](https://github.com/danielrose7/db-test-kit-js/blob/main/variants/prisma/src/tasks.ts) See [Caveats and escape hatches](/reference/caveats) for the other boundaries pinned by tests. --- # Fixtures # Fixtures Fixtures are the small, committed world that many tests are allowed to read. They load once before the suite and survive each test's rollback. Use them for stable identities and relationships that make tests easier to understand: two tenants, users with distinct roles, membership edges, and a representative domain record or two. Use a [factory](/reference/factories) when a record exists only to arrange one test. ## The decision rule | Put it in a fixture when… | Build it with a factory when… | |---|---| | Many tests need the same identity | One test owns the record | | Its label carries domain meaning | Its exact values are the variation under test | | It should be present before the test starts | The test should create or mutate it | | Relationships are shared reference context | The graph is specific to one scenario | Keep the baseline deliberately boring. A large fixture universe creates invisible coupling: changing one row can affect unrelated tests, and tests stop explaining the state they actually need. ## Declare a fixture set Each table gets one file. `fixtures()` checks every row against the table's insert type and adds a stable ID derived from the fixture-set name and label. ```ts import { organizations } from "@/schema"; import { FIXTURE_EPOCH } from "./clock"; import { fixtures } from "./runtime"; export const organizationFixtures = fixtures(organizations, "organizations", { acme: { name: "Acme", slug: "fx-acme", createdAt: FIXTURE_EPOCH }, other: { name: "Other Co", slug: "fx-other", createdAt: FIXTURE_EPOCH }, }); ``` Prefer a fixed fixture clock over `new Date()`. Stable data makes snapshots, ordering, and failure output repeatable. ## Refer to relationships by label Use `idOf()` for foreign keys. The fixture-set argument scopes identity, and TypeScript verifies the label. ```ts import { projects } from "@/schema"; import { organizationFixtures } from "./organizations"; import { fixtures, idOf } from "./runtime"; export const projectFixtures = fixtures(projects, "projects", { website: { organizationId: idOf(organizationFixtures, "acme"), name: "Website", }, }); ``` `idOf(organizationFixtures, "acmee")` fails typechecking. The loader also rejects a reference whose row is not included in the loaded fixture sets. ## Export a readable test API `test/fixtures/index.ts` exposes rows through `fx` and lists fixture sets in foreign-key order: ```ts export const fx = { organizations: organizationFixtures.rows, users: userFixtures.rows, projects: projectFixtures.rows, }; export const allFixtureSets = [ organizationFixtures, userFixtures, projectFixtures, ]; ``` Tests can then say `fx.users.olivia.id` or `fx.organizations.acme.id`. Parents must precede children in `allFixtureSets`; the loader deletes in reverse order and inserts forward. ## Loading and mutation The suite-level setup loads fixtures into committed state. Ordinary tests may read them and can even update or delete them inside the test transaction—the rollback restores the committed row afterward. Do not mutate fixture objects in JavaScript, and do not let a committed-mode test alter baseline rows. The loader is idempotent for its own deterministic IDs: it removes those rows, then inserts the declared sets. It is not a general database reset. The database safety checks still apply. ## Rails lineage The model comes directly from Rails fixtures: named shared records, label-based relationships, stable IDs, and transactional tests that return to the committed baseline. This implementation uses typed TypeScript modules and UUIDv5 instead of YAML/ERB and Active Record accessors. See [Rails testing ecosystem](/reference/lineage/rails) for the detailed comparison. ## Copy-ready review prompt ```text Review this repository's database-test fixtures using https://danielrose7.github.io/db-test-kit-js/reference/fixtures and https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md as the standard. Identify fixture rows that are test-specific and should become factories, unstable timestamps or generated values, raw foreign-key IDs that should use typed label references, incorrect parent-before-child load order, mutation of fixture objects, and committed-mode tests that can modify the shared baseline. Report findings with file paths and line numbers. Do not edit files, run destructive database commands, or assume that production and test databases are interchangeable. ``` --- # Factories # Factories Factories create variation owned by one test. They provide useful defaults while keeping the test free to override the values that matter. In this kit, Fishery supplies the factory API and the application's real ORM writes the record inside the current rollback transaction. Use a [fixture](/reference/fixtures) for a stable record that many tests share. ## Build and create mean different things `build()` returns a plain object and must not touch the database. `create()` runs the `onCreate` callback, persists through the application database seam, and returns the created record. ```ts import { Factory } from "fishery"; import { db } from "@/db"; import { newId } from "@/id"; import { organizations } from "@/schema"; interface OrganizationBuild { name: string; slug: string; } interface OrganizationRecord extends OrganizationBuild { id: string; } export const organizationFactory = Factory.define< OrganizationBuild, unknown, OrganizationRecord >(({ sequence, onCreate }) => { onCreate(async (build) => { const id = newId(); await db.insert(organizations).values({ id, ...build }); return { ...build, id }; }); return { name: `Org ${sequence}`, slug: `org-${sequence}-${newId().slice(-6)}`, }; }); ``` ```ts const draft = organizationFactory.build({ name: "Not persisted" }); const saved = await organizationFactory.create({ name: "Persisted in this test" }); ``` Keeping `build()` pure makes it safe for unit tests, request payloads, and expected values. It also makes a database write visible at the call site through `await ...create()`. ## Lazy associations A factory may create required related records, but only when the caller did not supply them. This keeps the convenient path short without forcing every test into a wasteful or irrelevant object graph. ```ts onCreate(async (build) => { const organizationId = build.organizationId ?? (await organizationFactory.create()).id; const projectId = newId(); await db.insert(projects).values({ id: projectId, organizationId, name: "Factory project", }); const id = newId(); await db.insert(tasks).values({ id, projectId, organizationId, title: build.title }); return { ...build, id, projectId, organizationId }; }); ``` When a shared fixture is the right parent, pass it explicitly: ```ts const task = await taskFactory.create({ organizationId: fx.organizations.acme.id, title: "Review the release", }); ``` The created task and any lazily created associations roll back together after the test. ## Defaults, sequences, and traits - Give every required field a valid default so the shortest factory call creates a valid record. - Use `sequence` or project ID helpers for uniqueness; do not rely on wall-clock time. - Use traits for a small number of meaningful, reusable states—not as a second domain model. - Accept explicit association IDs so callers can prevent implicit record creation. - Return the values actually persisted, including generated IDs and resolved associations. ## Failure modes Watch for factories that import an unmocked database client, write during `build()`, eagerly create an entire graph, hide authorization setup, or return a shape different from the stored row. The harness's seam guard should make the first mistake fail loudly outside a current transaction. Factory defaults should not become an unofficial fixture baseline. If many tests repeatedly create the same meaningful identity, promote only that stable context to a fixture and keep the variable records local. ## factory_bot lineage Fishery is explicitly inspired by factory_bot. This kit adopts factories, overrides, sequences, traits, and associations while adding an application-specific persistence boundary in `onCreate`. See [Rails testing ecosystem](/reference/lineage/rails) and [TypeScript prior art](/reference/lineage/typescript). ## Copy-ready review prompt ```text Review this repository's database-test factories using https://danielrose7.github.io/db-test-kit-js/reference/factories and https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md as the standard. Verify that build operations are pure, persistence occurs only in create hooks, database writes use the transaction-aware application seam, required associations are created lazily and can be supplied explicitly, defaults produce valid records, returned values match persisted values, and repeated shared identities belong in fixtures instead. Report findings with file paths and line numbers. Do not edit files or run destructive database commands. ``` --- # Caveats and escape hatches # Caveats and escape hatches The harness makes transaction behavior fast and convenient; it does not repeal transaction semantics. Each boundary below is pinned by a test in both variants where applicable. ## Expected failures abort transactions Postgres marks a transaction aborted after a failed statement. Wrap an error you intend to catch in an application-level nested transaction/savepoint. Be especially careful when application code catches its own insert error and then tries another query. ## One connection is not concurrency Queries issued through the wrapping transaction share one connection. A `Promise.all` can appear to pass while operations actually serialize. Move race-sensitive assertions into a committed-mode file and run them against real Postgres with data scoped to a tenant created by that test. ## Database time belongs to the transaction Postgres `now()` is the transaction start time. Rows inserted later in the same test may receive identical timestamps. Set explicit timestamps when order matters. Prisma's client-side `@default(now())` behaves differently; raw SQL time still follows Postgres. ## Baselines are visible globally Cross-tenant jobs and sweep queries see committed fixtures. Keep fixture dates in the past and workflow states terminal. Scope assertions to the test tenant instead of assuming the whole database is empty. ## Committed mode leaves data behind The real-Postgres database is disposable per run. A committed-mode test must create a unique tenant and must never depend on another committed test's cleanup. --- # Database safety # Database safety The default PGlite suite stores its database in the test process. The Postgres and Prisma paths can run migrations, delete fixture tables, and commit data. Treat their connection strings as destructive input. ## Required posture - Use a dedicated disposable database created for the test run. - Give its role access only to that database. - Name the database unmistakably as a test database. - Keep production and staging secrets unavailable to test jobs. - Print the selected host and database before destructive setup. - Fail closed when the environment does not explicitly identify itself as testing. - Never “make the tests pass” by weakening a connection-string guard. ## CI isolation The included workflow creates a Postgres service container visible only to the job. That is the preferred shape: migrations and committed-mode tests cannot reach application data because no application database credential exists in the job. ## Target-repository checklist Before loading fixtures, confirm all of these: - `NODE_ENV` is `test`; - the URL is not a production, preview, staging, or development URL; - the database is disposable; - migrations point at the same URL the tests use; - cleanup and committed-mode tests cannot run against a shared database; - the fixture role cannot connect to production. The reference is adding executable URL guards before its first public release. Until those land, the organizational isolation above is mandatory rather than optional. --- # Compatibility # Compatibility This project follows current stable releases rather than maximizing backward compatibility. “Tested” means exercised by the reference projects, not merely allowed by a version range. | Component | Tested reference | Policy | |---|---|---| | Node.js | 24 | Current stable/LTS line used by CI | | pnpm | 11.25.0 | Exact package-manager declaration | | TypeScript | 7.0.2 | Current stable used by both variants | | Vitest | 5.0.4 | Current stable; `aroundEach` requires at least 4.1 | | Drizzle ORM | 0.45.4 | Current stable at the last verification | | PGlite | 0.5.10 | Zero-setup Drizzle backend | | Prisma | 7.10.0 | Exact CLI/client/adapter pins in the variant | | Postgres | 16 | Local scripts and CI service image | Run `pnpm outdated` before a release. ORM, test-runner, and database upgrades require the full caveat suite and deliberate-failure checks; they should not be treated as lockfile-only maintenance. ## Explicit non-goals - MySQL, SQLite, MongoDB, and non-Postgres Drizzle dialects; - Prisma 8 until a dedicated variant is implemented and verified; - transparent support for arbitrary database client construction; - preserving support for old runners at the expense of the primary implementation. Older Vitest and Jest projects can use the hook-pair pattern in `RECREATE.md`, but the reference itself tracks the current stable Vitest design. --- # Sources and prior art # Sources and prior art Last reviewed: **October 15, 2026**. Version-sensitive behavior is also pinned by executable tests; documentation links provide context but do not replace those tests. This page is the compact source index. [Design lineage](/reference/lineage/) explains what the kit takes from each ecosystem, what it changes, and what it deliberately leaves behind. ## Primary documentation - [Vitest Test API](https://vitest.dev/api/test) — `aroundEach`, scoped fixtures, concurrency and runner behavior. - [VitePress deployment guide](https://vitepress.dev/guide/deploy) — static GitHub Pages build and repository base paths. - [Drizzle with PGlite](https://orm.drizzle.team/docs/connect-pglite) — the zero-service database used by the default reference suite. - [Drizzle Seed](https://orm.drizzle.team/docs/seed-overview) — deterministic generated data. It is a neighboring tool, not the same thing as a small label-addressed committed fixture baseline. - [Prisma 7 integration testing](https://www.prisma.io/docs/orm/v7/prisma-client/testing/integration-testing) — official real-database setup and suite-level seed/cleanup approach. - [Prisma 7 transactions](https://www.prisma.io/docs/orm/v7/prisma-client/queries/transactions) — interactive transaction limits and options. - [PostgreSQL transaction isolation](https://www.postgresql.org/docs/current/transaction-iso.html) — database semantics beneath both ORM implementations. ## Framework precedents - [Rails `ActiveRecord::FixtureSet`](https://api.rubyonrails.org/classes/ActiveRecord/FixtureSet.html) — label-based fixtures, stable IDs, associations, shared defaults and transactional tests. - [Django transactions in tests](https://docs.djangoproject.com/en/stable/topics/testing/tools/#django.test.TestCase) — isolation through transactions and rollback. - [Laravel database testing](https://laravel.com/docs/database-testing) — factories, seeders and database refresh patterns. - [Fishery](https://github.com/thoughtbot/fishery) — factory_bot-inspired TypeScript factories. ## Closest JavaScript prior art - [`jest-prisma`](https://github.com/Quramy/jest-prisma) — transaction-per-test and Prisma client seam. - [`vitest-environment-prisma-postgres`](https://github.com/codepunkt/vitest-environment-prisma-postgres) — maintained work extending the same family of Prisma/Vitest transaction patterns. ## Evidence boundary The project is a TypeScript port and composition of established testing practices, not a claim to have invented transactional tests, fixtures, or factories. Its original contribution is the worked combination: two current ORM examples, typed label references, a deliberate application database seam, real tenancy checks, executable caveat tests, committed-mode concurrency, and agent-readable adoption/update guidance. Performance claims should be framed qualitatively unless accompanied by a reproducible project-specific measurement. Transaction rollback avoids schema-wide cleanup work, so the advantage generally becomes more meaningful as a schema and suite grow; exact ratios depend on the database, schema, hardware and workload. --- # Design lineage # Design lineage db-test-kit-js is a TypeScript composition of mature database-testing practices. Its strongest lineage is Rails: a small committed fixture baseline, human-readable labels, deterministic identifiers, factories for variation, and a transaction rolled back after each test. Django and Laravel provide independent evidence that transaction-backed isolation is a durable framework pattern rather than a Rails peculiarity. The labels below keep the attribution precise: - **Direct lineage** means an API or design in this kit was consciously adapted from that source. - **Parallel precedent** means another ecosystem arrived at a similar practice independently. - **Kit-specific adaptation** means integration work needed to make the practice explicit and safe in a Vitest, TypeScript, ORM, and application-module environment. ## Idea map | Idea in this kit | Lineage | Where it appears here | Material difference | |---|---|---|---| | One rollback transaction per test | Rails direct lineage; Django and Laravel parallel precedent | `test/db/harness.ts`, `test/db/setup.ts` | A private thrown sentinel guarantees the ORM callback rolls back instead of committing | | A small committed baseline | Rails fixtures direct lineage | `test/fixtures/`, global setup | Fixtures are typed TypeScript rows rather than YAML interpreted by the ORM | | Stable IDs derived from labels | Rails `FixtureSet.identify` direct lineage | `test/fixtures/identify.ts` | UUIDv5 incorporates fixture-set identity as well as the label | | Relationships written as label references | Rails fixture labels direct lineage | `idOf(fixtureSet, "label")` | TypeScript checks that the label belongs to that fixture set | | Factories, traits, and lazy associations | factory_bot direct lineage, via Fishery | `test/factories/` | Persistence is isolated in `onCreate`; `build()` remains pure | | Explicit non-transactional tests | Rails opt-out direct lineage | `useCommittedDb()` and committed-mode suites | The escape hatch is restricted to disposable Postgres and owns cleanup | | Database reset alternatives | Django and Laravel parallel precedent | Caveat guidance and committed-mode cleanup | The kit does not hide truncation or migration behind its default path | | Current-transaction application seam | Kit-specific adaptation | mocked application `db` module and transaction context | Production imports keep working while tests fail closed outside a transaction | | Real authorization queries in tests | Kit-specific composition | session helper plus real membership query | Only identity lookup is replaceable; database authorization remains real | | Executable caveats and update headers | Kit-specific maintenance design | caveat tests, managed headers, `RECREATE.md` | The copied implementation carries its own boundaries and provenance | ## Why Rails is the primary reference Rails joins the relevant ideas into one established workflow. Transactional tests preserve a known database state; fixture labels describe shared records; `identify` turns a label into a stable ID; and the factory_bot ecosystem covers data that should vary per test. That combination is closer to this kit than any single JavaScript package. This is a port of the *testing model*, not of Rails syntax or global conventions. The kit keeps the useful division of responsibilities while exposing the database seam, transaction lifetime, opt-out path, and copy/update boundary as ordinary project code. Continue with [Rails testing ecosystem](/reference/lineage/rails), then compare [Django and Laravel](/reference/lineage/frameworks) and the available [TypeScript prior art](/reference/lineage/typescript). ## Copy-ready research prompt ```text Read the Design lineage section of the db-test-kit-js documentation, beginning at https://danielrose7.github.io/db-test-kit-js/reference/lineage/. Follow only its primary-source links. Produce a table with one row per db-test-kit-js feature and columns for classification (direct lineage, parallel precedent, or kit-specific adaptation), upstream source, local implementation file, and important semantic difference. Treat the repository's executable tests as the authority for current implementation behavior. Do not claim that db-test-kit-js invented transactional tests, fixtures, deterministic fixture IDs, or factories. Do not make numerical performance claims unless you also provide a reproducible benchmark and environment details. ``` --- # Rails testing ecosystem # Rails testing ecosystem Last reviewed against Rails **8.1.2** on October 15, 2026. Rails is the principal inspiration for this kit. The correspondence is not “Rails has tests too”; it is a specific data model for tests: committed shared fixtures, stable label-addressed identity, per-test transactions, and factories for local variation. ## Transactional tests Rails runs tests in database transactions by default and rolls those transactions back after the test. That restores the committed starting state without deleting every inserted row or rebuilding the schema. Rails also supports opting out when the behavior under test cannot live inside the wrapper transaction. db-test-kit-js adapts that lifecycle to Vitest's `aroundEach` and ORM callback APIs. The harness deliberately throws a private sentinel after the test body because a normally returned interactive-transaction callback commits. Only that exact sentinel is swallowed; application and assertion errors still fail the test. Primary source: [Testing Rails Applications — Transactions](https://guides.rubyonrails.org/testing.html#transactions). ## Fixtures as the common case Rails fixtures are predefined records loaded into the test database. Rails guidance positions them as shared default data, not as a way to spell every object a test might need. That boundary is retained here: fixtures cover the small, stable world many tests read; factories create records owned by one test. The kit does not copy Rails' YAML and ERB format. Fixture modules are TypeScript values checked against the application schema, and loader order is explicit. Primary source: [Testing Rails Applications — Fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures). ## Labels and deterministic identity `ActiveRecord::FixtureSet.identify(label)` gives a fixture label a stable identifier. Rails also lets one fixture refer to another by label, so relationships remain readable rather than embedding opaque IDs. The kit ports both ideas. `identify(fixtureSet, label)` derives a UUIDv5 from the fixture-set name and label; `idOf(fixtureSet, label)` preserves that readability while making an invalid label a TypeScript error. The fixture-set component prevents identical labels in different tables from sharing an ID. Primary source: [ActiveRecord::FixtureSet](https://api.rubyonrails.org/v8.1.2/classes/ActiveRecord/FixtureSet.html). ## Factories as the complement factory_bot is not Rails core, but it is the most direct ancestor of the factory half of the design. Its factories provide defaults, traits describe reusable variations, and associations build related records. Fishery brings that vocabulary to TypeScript. db-test-kit-js adds one firm boundary: `build()` is pure and persistence happens in `onCreate`. Lazy associations avoid creating a related graph when a test supplies an existing record. Primary sources: [factory_bot factory reference](https://thoughtbot.github.io/factory_bot/ref/factory.html), [traits with associations](https://thoughtbot.github.io/factory_bot/traits/with-associations.html), and [association reference](https://thoughtbot.github.io/factory_bot/ref/association.html). ## What this kit deliberately does not port - YAML/ERB fixture evaluation and model-shaped global fixture accessors. - Implicit application database replacement that can silently miss a second connection. - A claim that one wrapper transaction can test behavior requiring independent transactions. - Framework-owned magic that an application cannot inspect, copy, or adapt. The result should feel familiar to a Rails tester while remaining ordinary, explicit TypeScript. --- # Django and Laravel precedents # Django and Laravel precedents Django and Laravel are **parallel precedents**, not the direct source of the kit's API. Both reinforce the same architectural lesson: database isolation is a first-class test-runner concern, while fixtures, seeders, and factories serve different data-shaping jobs. ## Django Django's `TestCase` provides transaction-backed isolation and restores a known starting state. Its `fixtures` class attribute loads named data files for a test class. `TransactionTestCase` exists for tests that must observe transaction behavior directly, accepting the cost of resetting the database differently. The parallel with db-test-kit-js is the distinction between a fast default isolation path and an explicit path for transaction-sensitive behavior. The kit's `useCommittedDb()` is not a port of Django's class API, but it serves the same honesty: a wrapper transaction must not be used to “prove” cross-transaction behavior. Primary source: [Django 6.1 testing tools](https://docs.djangoproject.com/en/stable/topics/testing/tools/). ## Laravel Laravel's `RefreshDatabase` uses a transaction when the schema is current. Its documentation contrasts that with full migration or truncation approaches, which perform more reset work. Laravel also separates model factories from seeders: factories make test-specific records, while seeders populate broader known data. That resembles this kit's fixture/factory division, although the APIs and loading lifecycle differ. The kit loads a compact committed baseline once, then rolls back factory-created variation after each test. Primary source: [Laravel 13 database testing](https://laravel.com/framework/docs/13.x/database-testing). ## What the comparison supports Across Rails, Django, and Laravel, the recurring design is more important than any exact method name: 1. Establish a known database state. 2. Isolate ordinary tests with transactions when the database and test shape allow it. 3. Use a separate, explicit strategy for tests that must commit or coordinate connections. 4. Keep reusable baseline data distinct from per-test variation. db-test-kit-js packages those decisions as copyable project code because the TypeScript ecosystem does not provide one framework-owned lifecycle shared by Vitest, every ORM, and every application database seam. --- # TypeScript prior art # TypeScript prior art The TypeScript ecosystem contains strong pieces of this design, but they live at different layers. This kit combines them into a worked application pattern and keeps the seams visible. ## Runner and factory building blocks - [Vitest's Test API](https://vitest.dev/api/test) supplies `aroundEach`, scoped hooks, and the concurrency model used by the harness. - [Fishery](https://github.com/thoughtbot/fishery) supplies factory_bot-inspired factories for TypeScript. - [Drizzle Seed](https://orm.drizzle.team/docs/seed-overview) supplies deterministic generated data. It is useful neighboring work, but it is not the same abstraction as a small, committed, label-addressed fixture baseline. ## Transaction-focused packages - [`jest-prisma`](https://github.com/Quramy/jest-prisma) demonstrates transaction-per-test isolation and a Prisma client seam in Jest. - [`vitest-environment-prisma-postgres`](https://github.com/codepunkt/vitest-environment-prisma-postgres) continues that family of ideas for Prisma, Postgres, and Vitest. - [Prisma's integration-testing guide](https://www.prisma.io/docs/orm/v7/prisma-client/testing/integration-testing) documents real-database setup with suite-level seed and cleanup. These projects should be preferred when their abstraction matches the application. db-test-kit-js is most useful as a reference when the team wants the whole pattern in its own repository: baseline fixtures, factories, a current-transaction seam, real authorization coverage, committed-mode escape hatches, and executable caveat tests. ## The kit-specific integration work The novel value claimed here is deliberately narrow. It is not transactions, fixtures, or factories. It is the documented combination and the safety boundary around a copy-owned implementation: - ORM-specific harnesses that fail closed when code uses the database outside the active test transaction. - Typed fixture labels and deterministic IDs that work across Drizzle and Prisma examples. - An authorization test seam that replaces identity lookup without replacing the database decision. - Tests that demonstrate nested transaction, connection, timer, and concurrency limitations. - Version headers and an update procedure that distinguish managed reference code from local adaptations. See [Sources and prior art](/reference/sources) for the compact link index and [Compatibility](/reference/compatibility) for versions pinned by the executable examples. --- # Agent guide # Agent guide The repository is designed to be legible to coding agents without requiring the rendered site. ## Copy-ready prompts Every prompt on this site is intended to work as a single copy-and-paste block. Paths and commands are included in the prompt itself; surrounding prose is context, not a hidden instruction. ### Adopt the pattern Give an agent this prompt: ```text Read https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md completely. Recreate the applicable database-testing pattern in this repository. First report the existing database seam, migration path, ORM, transaction support, authorization boundary, test runner, and any existing harness/factories. Preserve working pieces and add only what is missing. Run every applicable Step 5 check, including the deliberate failing-test and seam-guard failure checks, and report exactly what ran. ``` ### Update a copied implementation ```text Read the "Updating an existing copy" section at https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md#updating-an-existing-copy and every newer entry in https://github.com/danielrose7/db-test-kit-js/blob/main/CHANGELOG.md than the version headers in this repository. Preserve all target-specific ADAPT changes and every EXAMPLE file. Apply only the reference delta, update the managed headers, and run the complete verification checklist. Before editing, summarize the files you expect to change. After editing, list every changed file, every check you ran, and any check you could not run. Do not publish a package or change production data. ``` ### Ask an agent to explain the lineage ```text Read https://danielrose7.github.io/db-test-kit-js/reference/lineage/ and its Rails ecosystem, Django and Laravel, and TypeScript prior art child pages. Explain which parts of the kit are direct adaptations of established framework practices, which are parallel precedents, and which are kit-specific TypeScript integration work. Cite the primary source links from those files. Do not describe db-test-kit-js as the inventor of transactional tests, fixtures, or factories, and do not make numerical performance claims without a reproducible benchmark. ``` ## Machine-readable entry points - [`llms.txt`](https://danielrose7.github.io/db-test-kit-js/llms.txt) is the short index. - [`llms-full.txt`](https://danielrose7.github.io/db-test-kit-js/llms-full.txt) concatenates the documentation into one text resource. - [`RECREATE.md`](https://github.com/danielrose7/db-test-kit-js/blob/main/RECREATE.md) is canonical for actions. - `skill/db-test-kit/SKILL.md` mirrors `RECREATE.md` for Agent Skills-compatible tools. ## Rules agents should not infer away - Do not publish or install the kit as a package. - Do not mock the authorization decision. - Do not access the application singleton outside the current transaction. - Do not run destructive setup against a non-disposable database. - Do not use a rollback test to claim concurrent behavior was tested. - Do not overwrite domain-specific fixtures and factories during an update.