vinta-ai-workflows 0.2.0 → 0.4.0

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/flask.md

@@ -0,0 +1,31 @@
+# Flask stack pack
+
+Flask-specific testing — the test client, app/request context, DB isolation. Loaded **only when the project is Flask**, alongside the runner pack (usually pytest). Read with the skill's universal rules.
+
+## App, client & context
+
+- Build the app from an **app factory** with a test config (`create_app({"TESTING": True, ...})`) so each test gets a clean instance; expose it as a fixture.
+- **`app.test_client()`** exercises the real routing/blueprint/error-handler stack — drive endpoints through it, don't call view functions directly.
+- Code that touches `current_app` / `g` / `session` needs an active context — use `with app.app_context():` / `with app.test_request_context():` in the fixture. Don't fake the context.
+
+## DB isolation
+
+- **SQLAlchemy:** bind the session to a connection-level transaction rolled back in teardown (connection → `begin()` → scoped session → `rollback` + `close`). Each test starts clean; no manual delete.
+- Prefer a real test DB over mocking the ORM.
+
+## Externals
+
+- **Auth:** log in through the client (post to the login route or set the session via `client.session_transaction()`), not by patching the auth check.
+- **HTTP:** `responses` / `respx` — never a real outbound call.
+- **Extensions (mail, tasks):** use the extension's test/suppress mode (`mail.record_messages()`, eager Celery) and assert on what it captured, rather than mocking send.
+- **Time/randomness:** `freezegun` or an injected clock; seed `random`.
+
+## Assertions
+
+- Assert `response.status_code` **and** the body (`response.get_json()` / rendered content) by full value. For JSON APIs assert the whole payload, not one key.
+
+## Pitfalls
+
+- Working outside an app/request context and getting `RuntimeError: working outside of ...` — push the right context in the fixture.
+- Reusing one app instance with mutable global state across tests — the factory per test avoids it.
+- Asserting only the status code while the body is wrong.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/medplum-test.globalSetup.ts

@@ -0,0 +1,54 @@
+// @ts-nocheck
+// Bundled verbatim from vintasoftware/medplum-snippet-catalog → TestSetup/test.globalSetup.ts
+// Source: https://github.com/vintasoftware/medplum-snippet-catalog/tree/main/TestSetup
+// Retrieved: 2026-07-31. The catalog is canonical — if it has advanced past this copy, prefer it.
+// Install as (e.g.) `src/test.globalSetup.ts` and register in Vitest config `test.globalSetup`.
+
+// Assert that the versions of @medplum/core, @medplum/definitions, @medplum/mock and
+// @medplum/fhirtypes match.
+import type { IndexedStructureDefinition } from '@medplum/core';
+import type { Bundle, SearchParameter } from '@medplum/fhirtypes';
+import type { TestProject } from 'vitest/node';
+
+export default async function setup(project: TestProject): Promise<void> {
+  // @medplum/core v5 references WebSocket at module-load time. This file runs in the Vitest
+  // main process, where WebSocket is only guaranteed as a global on Node >= 22.4. It has to be
+  // polyfilled *before* @medplum/core is loaded, which is why the imports below are dynamic and
+  // only the (erased) type imports sit at the top of the file.
+  if (typeof globalThis.WebSocket === 'undefined') {
+    try {
+      const ws = await import('ws');
+      (globalThis as Record<string, unknown>).WebSocket = ws.default ?? ws.WebSocket;
+    } catch {
+      throw new Error(
+        '@medplum/core needs a global WebSocket. Upgrade to Node >= 22.4, or add "ws" as a dev dependency.'
+      );
+    }
+  }
+
+  const { globalSchema, indexSearchParameterBundle, indexStructureDefinitionBundle } = await import('@medplum/core');
+  const { readJson, SEARCH_PARAMETER_BUNDLE_FILES } = await import('@medplum/definitions');
+
+  // Initialize FHIR
+  indexStructureDefinitionBundle(readJson('fhir/r4/profiles-types.json') as Bundle);
+  indexStructureDefinitionBundle(readJson('fhir/r4/profiles-resources.json') as Bundle);
+  indexStructureDefinitionBundle(readJson('fhir/r4/profiles-medplum.json') as Bundle);
+  for (const filename of SEARCH_PARAMETER_BUNDLE_FILES) {
+    indexSearchParameterBundle(readJson(filename) as Bundle<SearchParameter>);
+  }
+
+  // `globalSchema.types` is plain JSON-serializable data, so it can be handed to every test
+  // worker instead of each one re-reading and re-indexing the search parameter bundles.
+  // See test.setup.ts for the consuming side.
+  project.provide('globalSchemaTypes', globalSchema.types);
+}
+
+export function teardown(): void {
+  // Nothing to do.
+}
+
+declare module 'vitest' {
+  export interface ProvidedContext {
+    globalSchemaTypes: IndexedStructureDefinition['types'];
+  }
+}

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/medplum-test.setup.ts

@@ -0,0 +1,39 @@
+// @ts-nocheck
+// Bundled verbatim from vintasoftware/medplum-snippet-catalog → TestSetup/test.setup.ts
+// Source: https://github.com/vintasoftware/medplum-snippet-catalog/tree/main/TestSetup
+// Retrieved: 2026-07-31. The catalog is canonical — if it has advanced past this copy, prefer it.
+// Install as (e.g.) `src/test.setup.ts` and register in Vitest config `test.setupFiles`.
+// Requires its companion `test.globalSetup.ts` in `test.globalSetup` (it provides globalSchemaTypes).
+
+// Assert that the versions of @medplum/core, @medplum/definitions, @medplum/mock and
+// @medplum/fhirtypes match.
+import { globalSchema } from '@medplum/core';
+import { inject } from 'vitest';
+
+// This runs at module scope on purpose, not inside beforeAll. Vitest runs setup files once per
+// test file, but a test file's own module body is evaluated *before* any beforeAll hook
+// registered here. Fixtures built at module scope would otherwise search against an empty
+// schema and silently match nothing:
+//
+//   const medplum = new MockClient();
+//   await medplum.createResource({ resourceType: 'Patient', ... });
+//   const preloaded = await medplum.searchResources('Patient', 'family=Xu'); // 0 results
+const globalSchemaTypes = inject('globalSchemaTypes');
+
+if (!globalSchemaTypes) {
+  throw new Error(
+    'globalSchemaTypes was not provided. Add test.globalSetup.ts to `globalSetup` in your Vitest config.'
+  );
+}
+
+// Search parameters were indexed once by test.globalSetup.ts. `globalSchema.types` holds
+// nothing but plain data, so it survives the trip from the main process to this worker.
+// This is what MockClient's search matching reads, and it is the whole reason this file
+// exists: without it, filters like `family=` or `birthdate=` silently match nothing.
+globalSchema.types = globalSchemaTypes;
+
+// Structure definitions are deliberately *not* indexed here. MockClient indexes them itself
+// on its first write, so doing it up front only moves the same ~35 MB parse earlier.
+// The one exception: calling validateResource (or anything else that reads @medplum/core's
+// internal type store) before any resource has been created throws "Unknown data type".
+// Index them in that individual test if you need it.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/medplum.md

@@ -0,0 +1,47 @@
+# Medplum stack pack
+
+Medplum-specific testing — the mock client, FHIR resources, bots, React providers. Loaded **only when the project uses Medplum** (`@medplum/core` / `@medplum/react`), alongside the runner pack (Vitest / Jest). Read with the skill's universal rules.
+
+## Mock client, never a real server
+
+- **`MockClient` from `@medplum/mock`** stands in for `MedplumClient` — it holds an in-memory FHIR store, so `createResource` / `readResource` / `searchResources` run for real against fake data. Never point tests at a real Medplum server; there is no exception.
+- Give each test its own `MockClient` (or reset between tests) so resources one test creates don't leak into the next.
+- Seed only the resources the assertion needs; let the mock default the rest.
+
+## MockClient limitations — it is not a full FHIR server
+
+`MockClient` is an in-memory approximation. A green MockClient test does not prove the real server behaves the same — know the gaps:
+
+- **It comes pre-seeded.** MockClient ships with example resources already created (Patients, Practitioners, and others). An **unfiltered** `searchResources('Patient')` returns those *plus* what your test created — so **never assert on unfiltered search counts**. Filter to what your test made (a unique `identifier` / tag), or assert the specific resource by id/fields.
+- **Search support is partial.** Even with the FHIR index wired up (below), not every search parameter, modifier, chained search, `_include` / `_revinclude`, or `_filter` matches server semantics. Prefer filtering on simple, well-supported params in tests; if a filter behaves oddly, check server semantics before assuming your code is wrong.
+- **Server-only behavior isn't enforced.** Access policies / auth scoping, subscriptions, and some operations (`$everything`, GraphQL, batch/transaction edge cases) plus bot-execution nuances are approximated or absent. Anything whose contract depends on the server enforcing it belongs in an integration/e2e test, not a MockClient unit test.
+- **Consult the team's MockClient extensions + internal Medplum testing docs** for the current maintained limitation list and any local wrappers that patch gaps — they track the Medplum version. Canonical setup + helpers live in the `medplum-snippet-catalog`.
+
+## Search filtering — indexed once at setup, never per test
+
+- **`MockClient` search filters only work if the FHIR search parameters are indexed in the test process.** Symptom: a resource comes back from an unfiltered `searchResources`, but `searchResources` / `searchOne` **with** a filter (`family=`, `birthdate=`, …) silently returns nothing. That means the index is missing, not that your data is wrong.
+- This is wired **once** at bootstrap via two Vitest setup files: `test.globalSetup.ts` (indexes the bundles once in the main process, shares `globalSchema.types` to workers) registered under `test.globalSetup`, and `test.setup.ts` (assigns the shared index at module scope) registered under `test.setupFiles`. **Do not add `indexStructureDefinitionBundle` / `indexSearchParameterBundle` inside a test or a per-test `beforeAll`** — rely on the project-level setup. If filters mysteriously fail, check both files are registered in `vitest.config.*`, not that each test indexes.
+- One deliberate exception: `validateResource` (or anything reading @medplum/core's type store) **before any resource is created** throws `Unknown data type` — index structure definitions in that one test if you hit it.
+- Version alignment matters: `@medplum/core`, `@medplum/definitions`, `@medplum/mock`, and `@medplum/fhirtypes` must be on **matching versions** — a skew causes confusing index/search failures.
+
+## FHIR resource assertions
+
+- Assert on the **resource fields you care about by value** — `patient.name[0].family`, `observation.valueQuantity.value` — not just `resource.id` truthiness or a search count. A wrong resource with an id still passes a truthiness check.
+- When asserting a search result, assert the matched resources' contents, not only `bundle.entry.length`.
+- Build resources as typed `@medplum/fhirtypes` objects (or a small factory helper), not loosely-typed literals copied across tests.
+
+## Bots
+
+- A bot's `handler(medplum, event)` is a plain function — unit-test it by calling it with a `MockClient` and a constructed `BotEvent` input, then assert the resources it wrote (read them back from the mock) and the value it returned.
+- Mock outbound integrations the bot calls (external HTTP, `sendEmail`) at the boundary; don't mock the `medplum` client — use `MockClient`.
+
+## React components (with `@medplum/react`)
+
+- Wrap rendered components in **`MedplumProvider` with a `MockClient`** (Testing Library). Query by role/text; assert rendered output. See the runner pack's Testing Library notes.
+- Let components fetch through the `MockClient`; use `await screen.findBy...` for the async load rather than mocking the fetch.
+
+## Pitfalls
+
+- Sharing one `MockClient` across tests without reset — resources bleed between tests.
+- Asserting `resource.id` is defined instead of the fields the code set.
+- Mocking `MedplumClient` methods by hand instead of using `MockClient` — you re-implement the store and test the mock.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/nextjs.md

@@ -0,0 +1,27 @@
+# Next.js stack pack
+
+Next.js (App Router) testing — what to unit-test vs leave to e2e, route handlers, server code. Loaded **only when the project uses Next.js**, alongside the runner pack (Vitest / Jest) and, for UI, the React stack pack. Read with the skill's universal rules.
+
+## Test the logic, not the framework
+
+- **Unit-test the units the framework calls**, not the framework's rendering: route-handler functions, server actions, data-loading helpers, and pure client components. Full-page rendering, navigation, streaming, and middleware are e2e territory (Playwright) — don't fake the Next runtime to force them into a unit test.
+
+## Route handlers & server actions
+
+- A **Route Handler** (`GET`/`POST` in `route.ts`) is a plain async function taking a `Request` — call it directly with a constructed `new Request(url, { method, body })` and assert the returned `Response` (`await res.json()` + `res.status`) by full value. No server boot needed.
+- A **Server Action** is a plain async function — call it with its args and assert what it returned / wrote (mock the DB/service boundary, not the action). Don't assert on `revalidatePath`/`redirect` internals; assert the effect.
+- Inject or mock external services (DB, upstream APIs) at the boundary with MSW / a fake client, not by faking `next/*` internals.
+
+## Client components & hooks
+
+- Test client components with the React stack pack (Testing Library). Mock `next/navigation` (`useRouter`, `useSearchParams`, `usePathname`) with light fakes when a component reads them — assert the visible result, not that `router.push` was called, unless navigation *is* the contract.
+
+## Server components
+
+- Async Server Components that just fetch + compose are thin — extract the data logic into a plain function and unit-test that. Rendering the RSC tree itself is not well-served by unit tests today; cover it with e2e.
+
+## Pitfalls
+
+- Trying to render a whole App-Router page in a unit test and mocking half of Next to do it — brittle; use e2e.
+- Asserting `redirect()` / `revalidatePath()` were called instead of the observable outcome.
+- Leaving real `fetch` calls in a Server Component test — stub at the network layer (MSW) or test the extracted function.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/prisma.md

@@ -0,0 +1,31 @@
+# Prisma stack pack
+
+Prisma (data layer) testing — DB isolation, real-DB vs mock, seeding. Loaded **only when the project uses Prisma** (`@prisma/client`), alongside the runner pack (Vitest / Jest) and any web-framework stack pack. Read with the skill's universal rules.
+
+## Real test DB over a mocked client
+
+- **Test queries against a real (SQLite/Postgres) test database**, not a mocked `PrismaClient`. Mocking the client (`jest-mock-extended`, `prisma-mock`) means your `where`/relations/constraints/`select` never run — the test passes on a query that would throw in production. Point `DATABASE_URL` at a disposable test DB and apply migrations in global setup (`prisma migrate deploy` / `db push`).
+- **Mock only at the port, not the client.** If the unit under test is pure business logic that takes a repository/port, inject a fake repo — don't mock `PrismaClient`. If you're testing the query/persistence itself, use the real DB.
+
+## DB isolation
+
+- **Wrap each test in a transaction rolled back at teardown** — an interactive `$transaction` handle passed to the code, rolled back after (helpers like `@chax-at/transactional-prisma-testing` automate it), or a per-test truncation of the tables touched. Each test starts clean; no manual delete scattered around.
+- **`$disconnect()` in teardown** (global) — leaked connections exhaust the pool and hang the suite.
+- Never depend on test ordering or on rows another test created.
+
+## Test data
+
+- Seed with small factory helpers that spell out only the fields the assertion needs and let schema defaults fill the rest — not deep nested `create` literals copy-pasted across tests.
+- Reset to a known baseline between tests via the rollback/truncate above, not a shared mutable seed.
+
+## Assertions
+
+- **Read the row back and assert its fields by value** (`await prisma.user.findUnique(...)` → assert the object), not `count` alone — a count passes for the wrong row. For relations, `include` them and assert their contents.
+- After a write, assert the persisted state from a fresh read, not the in-memory input you passed in.
+
+## Pitfalls
+
+- Mocking `PrismaClient` then asserting the mock was called — tests the mock, not the query.
+- `expect(await prisma.x.count()).toBe(1)` as the whole assertion — asserts a count, not the right record.
+- No `$disconnect()` / shared client across tests — connection leaks and cross-test bleed.
+- Truncating in `beforeEach` as a cleanup crutch instead of transaction rollback — slower and hides ordering bugs.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/python-package.md

@@ -0,0 +1,28 @@
+# Python package (library) stack pack
+
+Testing a pure Python library/package — no web framework, no app DB, shipped to consumers (e.g. an open-source package). Loaded **only when the project is a standalone package**, alongside the pytest runner pack. Read with the skill's universal rules.
+
+## Test the public API
+
+- Test the package's **public surface** — the names in `__init__.py` / documented exports — the way a consumer imports and calls them. Don't reach into private modules (`_internal`) to test them directly; if a private helper needs its own test, that's a hint it should be public or covered through the public path.
+- Backward compatibility is the contract: a test pinning documented behavior is what stops a refactor from breaking downstream users.
+
+## Keep it dependency-light & deterministic
+
+- A library test should need only the package + `pytest` (+ its declared test extras). Don't pull a DB, a broker, or network into a unit test — if a feature integrates with those, test the seam with a fake/in-memory double the consumer could also use.
+- No hidden global state between tests: reset module-level singletons/caches your code exposes; don't rely on import order.
+
+## Data & purity
+
+- Most of a library is pure functions — arrange literal inputs, assert literal outputs by full value. Parametrize to cover edge cases (empty, boundary, unicode, `None`).
+- For anything time/random/env-dependent, inject the dependency (clock, rng, `os.environ` reader) so tests pass a fake — libraries especially should not read ambient globals.
+
+## Version / matrix awareness
+
+- If the package supports multiple Python versions or an optional-dependency matrix (`tox` / `nox`), write tests that don't assume the newest syntax/behavior, and guard optional-dependency paths with `pytest.importorskip` so the suite runs in every configured environment.
+
+## Pitfalls
+
+- Testing `_private` internals — couples the test to today's structure and breaks on refactor.
+- A unit test that imports a heavy optional dependency unconditionally — fails in the minimal matrix env.
+- Asserting truthiness of a returned object instead of its value/shape.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/react-router.md

@@ -0,0 +1,25 @@
+# React Router stack pack
+
+React Router testing — data-router loaders/actions and routing-aware components. Loaded **only when the project uses React Router** (`react-router` / `react-router-dom` / `@react-router/*`), alongside the runner pack and, for UI, the React stack pack. Read with the skill's universal rules.
+
+## Loaders & actions are plain functions
+
+- In data-router / framework mode, a route's **`loader` and `action` are plain async functions** receiving `{ request, params, context }`. Export and call them directly; assert what they return / throw. A thrown `redirect(...)` is part of the contract — assert its `Location`, don't assert on router internals.
+- Mock the boundary the loader/action hits (DB, upstream API) with a fake client / MSW. Build the `request` with `new Request(url, { method, body })` for actions.
+
+## Routing-aware components
+
+- Components that call routing hooks (`useNavigate`, `useParams`, `useLoaderData`, `<Link>`) need a router in the test. Use **`createMemoryRouter([...routes], { initialEntries: [...] })` + `<RouterProvider>`** (data router), seeding the route with `loader: () => data` so `useLoaderData` returns what the component reads. For simple hook-only components, wrapping in **`<MemoryRouter initialEntries={[...]}>`** is enough.
+- Assert the **visible result** of navigation (the destination content rendered, the URL via the test router), not that `navigate` was called — unless firing navigation *is* the unit's whole job.
+
+## Externals & isolation
+
+- Stub HTTP at the network layer with MSW; never a real outbound call.
+- Build a **fresh memory router/history per test** — a shared router leaks navigation/loader state and causes order-dependence.
+
+## Pitfalls
+
+- Rendering a component that uses `useNavigate` / `<Link>` without a router wrapper → it throws; wrap it in a memory router.
+- Asserting `navigate("/x")` was called instead of asserting the `/x` content rendered.
+- Testing loaders by rendering the whole route tree instead of calling the loader function directly.
+- Reusing one router across tests — stale location/loader data flips results by order.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/react.md

@@ -0,0 +1,29 @@
+# React stack pack
+
+Component-testing idioms with React Testing Library. Loaded **only when the project renders React UI**, alongside the runner pack (Vitest / Jest). Read with the skill's universal rules.
+
+## Query & interact like a user
+
+- **Query by role/label/text**, not test-ids or class names: `getByRole("button", { name: /save/i })`. Test-ids couple the test to markup. Reserve `data-testid` for the rare element with no accessible handle.
+- **`getBy`** (must exist) vs **`queryBy`** (assert absence) vs **`findBy`** (async, awaited). Use the right one — `getBy` throwing is a clearer failure than a null deref.
+- Drive interactions with **`user-event`** (`await userEvent.click(...)`), not raw `fireEvent` — it models real focus/typing.
+
+## Assert output, not internals
+
+- Assert what the user sees (rendered text, presence/absence, disabled state), not component state, not that a hook or handler ran, not render counts. The test should survive a refactor that preserves behavior.
+- Don't reach into instance internals or snapshot the whole tree as the only assertion — assert the elements that matter.
+
+## Data & async
+
+- Mock HTTP at the network layer with **MSW** (see the runner pack), so components run their real fetch path. For a component that loads data, `await screen.findBy...` the settled UI rather than mocking the fetching hook.
+- Pure logic (reducers, formatters, custom hooks without UI) — test directly, no render. Hooks: `renderHook` + `act`.
+
+## Isolation
+
+- Clean up is automatic per test with the Testing Library auto-cleanup; don't share rendered state between tests. Reset mocks in `afterEach` (see runner pack).
+
+## Pitfalls
+
+- `getByTestId` everywhere — brittle, and hides accessibility gaps. Prefer role/label.
+- Asserting a handler prop was called instead of the visible result of calling it.
+- Missing `await` on `findBy` / `userEvent` — the assertion runs before the UI settles and passes hollow.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/tanstack-start.md

@@ -0,0 +1,32 @@
+# TanStack Start stack pack
+
+TanStack Start testing — server functions, route loaders, and isomorphic logic. Loaded **only when the project uses TanStack Start** (`@tanstack/react-start`), alongside the runner pack (Vitest) and, for UI, the React stack pack. Read with the skill's universal rules.
+
+## Test the logic, not the framework
+
+- **Unit-test the units the framework calls**, not the full route/SSR render: server functions, route `loader` / `beforeLoad` functions, and pure components. Full-page rendering, streaming, hydration, and navigation are e2e territory (Playwright) — don't fake the Start runtime to force them into a unit test.
+
+## Server functions (`createServerFn`)
+
+- A server function's **handler is a plain async function** — export it (or the plain function it wraps) and call it directly with constructed input; assert the returned value by full shape. Don't spin up the server to test it.
+- Mock what the handler calls at the boundary (DB, upstream APIs) with a fake client / MSW, not the `createServerFn` machinery.
+- Validate the input-validator (`.validator(...)`) separately with valid + invalid inputs — it's a pure function.
+
+## Route loaders & context
+
+- A route's `loader` / `beforeLoad` is a plain async function receiving `{ context, params, ... }` — call it with a constructed argument and assert what it returns / throws (e.g. a `redirect()`), passing a fake `context` (auth principal, injected client). Don't assert on router internals; assert the returned data or the thrown redirect's target.
+
+## Client components & router hooks
+
+- Test client components with the React stack pack (Testing Library). For components using router hooks (`useLoaderData`, `useNavigate`, `useParams`), render them under a **test router** built with `createRouter` + a `createMemoryHistory({ initialEntries: [...] })` and `RouterProvider`, seeding the route with the data the component reads. Assert the visible result, not that `navigate` was called (unless navigation *is* the contract).
+
+## Externals & isolation
+
+- Stub HTTP at the network layer with MSW; never a real outbound call in a unit test.
+- Fresh router/history per test — don't share navigation state between tests.
+
+## Pitfalls
+
+- Booting the Start server or rendering a whole route in a unit test and mocking half the framework — brittle; use e2e.
+- Asserting a `redirect()` / `navigate()` happened instead of the observable outcome (the data, the rendered target).
+- Leaving a real `fetch` in a server-function or loader test — stub at the boundary or test the extracted function.

package/skills/vinta-derive-skills/resources/write-unit-test-packs/stacks/typescript-package.md

@@ -0,0 +1,32 @@
+# TypeScript package (library) stack pack
+
+Testing a pure TypeScript library/package — no framework, no app DB, shipped to consumers (npm package, workspace lib). Loaded **only when the project is a standalone package**, alongside the runner pack (Vitest / Jest). Read with the skill's universal rules.
+
+## Test the public API
+
+- Import from the package **entry point** (`exports` / `main` / the package name in a monorepo), the way a consumer does — not deep relative paths into `src/internal`. That's what pins the published contract; a green suite that imports internals can still ship a broken public API.
+- If a private helper needs its own test, consider whether it should be exported, or cover it through the public path.
+
+## Types are part of the contract
+
+- Type-level behavior (generics, inference, conditional types) won't be caught by value assertions. When it matters, add compile-time type tests with **`tsd`** / `expectTypeOf` (Vitest) / `vitest`'s type-testing — assert that a call *doesn't* compile when it shouldn't and infers the right type when it should.
+
+## Keep it dependency-light & deterministic
+
+- A library test needs only the package + the runner. Don't pull a DB/network in; test integration seams with an in-memory fake the consumer could also use.
+- Reset any module-level singleton/cache the package exposes between tests; don't rely on import order.
+
+## Build outputs (when relevant)
+
+- If the package ships both ESM and CJS, a small smoke test that imports the built entry in each format catches packaging/`exports`-map breakage that source-only tests miss.
+
+## Data & purity
+
+- Most of a library is pure — literal inputs, assert literal outputs with `toEqual` / `toStrictEqual` (use `toStrictEqual` when `undefined` fields / class identity are part of the contract). Table-drive edge cases (empty, boundary, unicode).
+- Inject clock/rng/env for anything ambient so tests pass a fake.
+
+## Pitfalls
+
+- Testing via deep `src/...` imports — green tests, broken published `exports`.
+- Only value tests on a type-heavy API — the type regressions ship silently. Add type tests.
+- `toEqual` when `undefined`-property presence matters — use `toStrictEqual`.

package/skills/vinta-derive-skills/resources/write-unit-test-template.md

@@ -0,0 +1,44 @@
+---
+name: write-unit-test
+description: Write a unit test for a function, method, class, or module in {{PROJECT_NAME}} ({{STACK_SUMMARY}}) — mock only genuine externals, assert the full output (not counts/truthiness), clean up created data or roll back the transaction, never hit a service unavailable in dev/test, keep test logic literal, stay decoupled from internals. Applies this project's test preferences and the runner + stack packs for {{FRAMEWORK_PACKS_LIST}}. Use on "add a test", "write a unit test", "cover this with tests", or when new behavior lands uncovered.
+---
+
+# Write a unit test
+
+A test should fail when the behavior breaks and pass when it's correct — nothing more.
+
+## Steps
+
+1. **Read the unit's contract** — inputs, outputs, side effects, error paths. Test the contract, not the implementation.
+2. **Match the nearest existing tests** — location, naming, helpers — unless they break a rule below.
+3. **Load the packs** that shipped for this project — the test-**runner** pack (how to structure/assert/mock) plus the **stack** pack(s) matching what you're testing (DB isolation, framework client, domain mocks). Follow them alongside the rules:
+
+{{FRAMEWORK_PACK_LOADER_BLOCK}}
+
+4. **Write it, then prove it.** Run in isolation (`{{NEW_TEST_CMD_PATTERN}}`) — green. Break the code (or invert an assertion), re-run — red for the right reason. Revert. Run the suite (`{{TEST_CMD}}`){{SCOPED_TEST_NOTE}} — still green.
+
+## Rules
+
+1. **Mock only genuine externals** (third-party HTTP, payment/email/SMS, clock, randomness). Never mock the unit under test, its local collaborators, the DB, or your own pure functions.
+2. **Assert the full value**, not counts or truthiness. `assert result`, `toBeTruthy()`, `len(x) == 3` are too weak. Assert contents and order for collections. **But don't over-fit brittle text** — for human-facing strings (error messages, UI copy, i18n) assert a stable anchor (an error code/type, a role, an i18n key, a substring), not the exact prose that churns.
+3. **Leave no trace** — transaction-rollback harness where available; else clean up in teardown, and make teardown run on failure. Never depend on another test's data.
+4. **No external service** that can't run in dev/test. Stub at the boundary.
+5. **Test logic stays literal** — no loops/conditionals computing the expected value. Parametrize to cover cases; keep each expectation a literal.
+6. **Decouple from internals** — assert observable state/output, not private methods or call counts. The test survives a behavior-preserving rewrite.
+7. **One behavior per test**, named for what it pins (`returns_zero_for_empty_cart`).
+8. **Kill nondeterminism** — control every entropy source (clock, randomness, timezone/locale, iteration/DB order, concurrency). Freeze/inject them; a test that passes only sometimes is worse than none.
+9. **Cover the branches, not just the happy path** — aim high (95%+ branch coverage): each error path, guard, and edge (empty, boundary, null) gets a case. Coverage is the floor, correct assertions are the point.
+
+## Project preferences
+
+Apply these; `framework-default` defers to the pack. If the existing suite contradicts a preference, follow the preference for new tests and flag it — don't rewrite old tests.
+
+{{PROJECT_TEST_PREFERENCES_BLOCK}}
+{{ADDITIONAL_CONVENTIONS_BLOCK}}
+
+## Pitfalls
+
+- Asserting on a mock you set up — tests the mock, not the code.
+- Giant snapshots as a substitute for asserting the fields that matter.
+- `delete all rows` in setup instead of rollback — masks leaked state, races other tests.
+- Testing the framework/ORM/language instead of your behavior on top of it.