@flefebvre/prisma-test-helper 0.1.0 → 0.2.0

package/README.md

@@ -23,7 +23,9 @@ back.
 
 ## Requirements
 
-- Node >= 20, ESM project
+- Node >= 20. The package ships ESM only, but your project need not be — the wiring runs
+  under Vitest, which transforms modules through Vite, so a CommonJS project (a stock
+  Next.js app, say) works too.
 - Docker (or another container runtime Testcontainers can reach)
 - Peer dependencies: `vitest` ^4 and `prisma` ^7, with your migrations committed
   (`prisma migrate deploy` is what the harness runs)
@@ -116,7 +118,8 @@ vi.mock("../src/db/client.js", async (importOriginal) => {
 
 The factory returns `{ db }` because the client module above exports only `db`. If yours
 exports anything else — types, a re-exported `Prisma` namespace, helpers — spread the
-original too, or those exports become `undefined` at every call site:
+original too, or every call site touching one of them fails with Vitest's
+`No "Prisma" export is defined on the "../src/db/client.js" mock`:
 
 ```ts
 return { ...actual, db: installTestTransaction(actual.db, databaseUrl, databaseName) };
@@ -220,9 +223,9 @@ Opts a test file into the database. Wraps every test in its own transaction: a
 
 ### `isDatabaseSetUp(): boolean`
 
-Whether `setupDatabase()` has run in this file. Factories read it to fail loudly when a
-file forgot to opt in, rather than run outside any transaction — where their writes would
-commit.
+Whether `setupDatabase()` has run in this file. Useful in your own fixture helpers — read
+it to fail loudly when a file forgot to opt in, rather than let them run outside any
+transaction, where their writes would commit.
 
 ```ts
 if (!isDatabaseSetUp()) {
@@ -233,16 +236,18 @@ if (!isDatabaseSetUp()) {
 ### `registerResetHook(hook): void`
 
 Register a callback to run in every `beforeEach`, after the transaction opens. This is the
-seam factories plug into. Hooks receive `{ testName, seed }`, where `seed` is a
-deterministic 32-bit hash (FNV-1a) of the test name alone — never the worker id, the file,
-or the run order. Rerunning one test with `-t` therefore hands it the same seed a
-full-suite run did.
+seam for wiring your own fixture and test-data libraries into the per-test lifecycle —
+reseeding a random generator, resetting a counter, priming a fixture registry. Hooks
+receive `{ testName, seed }`, where `seed` is a deterministic 32-bit hash (FNV-1a) of the
+test name alone — never the worker id, the file, or the run order. Rerunning one test with
+`-t` therefore hands it the same seed a full-suite run did.
 
-Faker is deliberately **not** a dependency of this package; the harness only hands you the
-seed.
+No data-generation library is a dependency of this package; the harness only hands you the
+seed, and you decide what to do with it. Below, Faker — but anything that takes a numeric
+seed works the same way.
 
 ```ts
-// tests/factories.ts
+// tests/fixtures.ts
 import { faker } from "@faker-js/faker";
 
 import { registerResetHook } from "@flefebvre/prisma-test-helper";
@@ -252,7 +257,7 @@ registerResetHook(({ seed }) => {
   faker.seed(seed);
 });
 
-export function buildAuthor() {
+export function createAuthor() {
   return db.author.create({ data: { name: faker.person.fullName() } });
 }
 ```
@@ -292,6 +297,25 @@ Every error below comes from this package. Find the one you got.
 | `a test transaction is already live —`                                  | `setupDatabase()` was called twice in one file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `the database was touched with no test transaction live —`              | The file never called `setupDatabase()`, or data was built in `beforeAll` instead of inside a test.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
+## Agent skills
+
+If you use an AI coding agent (Claude Code, Cursor, Codex, …), this repo ships two installable skills that teach it this harness — split so you keep only what you still need:
+
+| Skill                                                                  | What it does                                                                                                                                                                                                                                                            | Keep it?          |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| [`prisma-test-helper-setup`](skills/prisma-test-helper-setup/SKILL.md) | Wires the harness into a project: installs the package, finds your Prisma client module, scaffolds the five files above (merging existing configs rather than clobbering them), pins the Postgres image from your `docker-compose.yml`, and verifies with a smoke test. | Remove once wired |
+| [`prisma-test-helper`](skills/prisma-test-helper/SKILL.md)             | The rules for writing tests in a wired project: the per-file `setupDatabase()` opt-in, where test data belongs, the Reset Hook seam, and every guard error above with its fix.                                                                                          | Keep installed    |
+
+```sh
+# wiring a project for the first time
+npx skills add flolefebvre/prisma-test-helper --skill prisma-test-helper-setup
+
+# writing tests in a project that is already wired
+npx skills add flolefebvre/prisma-test-helper --skill prisma-test-helper
+```
+
+(Uses the [skills CLI](https://github.com/vercel-labs/skills); or just copy the skill directory into your agent's skills directory, e.g. `.claude/skills/`.)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flefebvre/prisma-test-helper",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Throwaway-Postgres test harness for Prisma + Vitest: one container per run, one database per worker. Postgres-only.",
   "type": "module",
   "license": "MIT",