Testing

How the template's tests are laid out, what ./verify.sh runs, and the guard specs that fail when a change skips a step. Read it before writing a spec, or when verify fails and you need to know which rule you broke.

What ./verify.sh runs

Run it from the repository root, after npm ci in backend/ and frontend/. The stages run in this order, and the first stage that fails stops the run:

1. Integration database. If you set TEST_DATABASE_URL, verify uses it. Otherwise, if Docker answers, it starts a throwaway postgres:16-alpine container on a free 127.0.0.1 port, with its data in memory, runs npm run migrate against it and exports TEST_DATABASE_URL. The container is removed when verify exits. With no Docker, this stage is skipped.
2. Backend, in backend/: format:check, lint, knip, build, then npm run test. The tests are killed after VERIFY_TEST_TIMEOUT_SECONDS (default 900), which is what a spec that leaves a handle open looks like.
3. Frontend, in frontend/: format:check, lint, knip, test, the type drift check, then build.
4. OpenAPI drift: boots the backend's module graph with stub env values, writes backend/openapi.runtime.json and diffs it against the committed openapi.json.
5. Dependencies: npm audit --omit=dev --audit-level=critical in each half. Only a critical advisory fails it. If the npm registry does not answer, the half prints SKIPPED - the registry did not answer.

The last line is the verdict. verify: all green (integration specs ran) means the integration specs ran. It does not cover the audit: a half whose audit printed SKIPPED still ends green, so read the dependencies lines too. The verify flags (VERIFY_QUIET=1, VERIFY_ALLOW_INTEGRATION_SKIP=1 and the timeouts) are in AGENTS.md.

Unit and integration specs

Backend specs use jest and sit beside the file they test:

npm run test runs two jest passes: first every plain spec in parallel, then the integration and HTTP specs one file at a time (--runInBand), because they share one database.

An integration spec gates itself like this, so copy the pattern:

const describeIfDb = hasTestDb ? describe : describe.skip;

Without TEST_DATABASE_URL the second pass reports skips instead of failures:

Test Suites: 20 skipped, 1 passed, 1 of 21 total
Tests:       155 skipped, 14 passed, 169 total

and verify ends verify: NOT green - integration specs skipped. A skipped run has not tested any SQL.

Frontend tests use vitest. frontend/vitest.config.mts collects only *.test.ts at the root, under lib/ and under app/. They cover lib/ helpers, Server Actions (app/**/actions.test.ts) and auth.ts. There is no component-test setup: a *.test.tsx file is never collected, and npm run test -- app/x.test.tsx prints No test files found, exiting with code 1.

Where a new spec goes

• A backend unit spec: beside the source, same name plus .spec.ts (items.service.ts gets items.service.spec.ts).
• A backend spec that needs SQL: <name>.integration.spec.ts, using connectTestDb() and closeTestDb() from src/db/integration-test-db.ts and the describeIfDb gate above. src/items/items.service.integration.spec.ts is the one to copy. The specs delete rows, so point them at a database you can lose.
• A frontend test: <name>.test.ts beside the file in lib/ or app/.

Running one file

From backend/:

npm run test:jest -- src/common/route-auth.spec.ts

Run single files through test:jest: it adds the --experimental-vm-modules flag the NestJS packages need.

An integration spec needs a migrated database. With the dev Postgres running (docker compose up -d --wait postgres), create a separate test database in it once, then run the spec, from backend/:

docker compose exec postgres createdb -U postgres crabstack_test
export TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5433/crabstack_test
DATABASE_URL="$TEST_DATABASE_URL" npm run migrate
npm run test:jest -- src/items/items.service.integration.spec.ts

From frontend/:

npm run test -- lib/billing.test.ts

The guard specs

These specs check rules that span the codebase. Adding a module trips them by design: each one stands for a decision that would otherwise go unmade.

backend/src/common/route-auth.spec.ts

The spec walks AppModule's imports for every controller Nest registers, whatever its file or class is called, and each needs an entry in POLICY, keyed by class name. Most list each route with the guards it requires (SESSION, ADMIN, INTERNAL) or a string saying why it is public. An entry with classGuards (the two /internal/* controllers) lists no routes: every route on it, including one added later, must carry exactly those guards. The test reads the guards each route actually carries and compares.

So a new controller takes one edit in this file, its POLICY entry. Add the route auth policy has the walkthrough.

backend/src/users/deletion-policy.spec.ts

Reads every createTable in backend/migrations/ and requires an entry for each table in DELETION_POLICY (backend/src/users/deletion-policy.ts): what account deletion does to it, or why it needs nothing.

backend/src/users/deletion-policy.integration.spec.ts

Checks the columns lists against the real schema, so it needs TEST_DATABASE_URL. A column that exists but is in neither erased nor kept fails with "notes.user_id is unlisted: add it to erased or kept"; a listed column that does not exist fails with is listed but does not exist. Recipe 1 step 6 covers which list a column belongs in.

The MCP tool specs

backend/src/mcp-admin/mcp-admin-tools.service.spec.ts pins the exact list of registered admin MCP tools, and checks that get_server_info mentions every one. mcp-admin-ops-tools.service.spec.ts pins only the tools McpAdminOpsToolsService registers, with their annotations. Registering a new ops tool and nothing else fails three tests. A new tool needs:

• the safeTool(...) registration,
• its row in OPS_SERVER_INFO_TOOLS (ops tools, in mcp-admin-ops-tools.service.ts) or registerServerInfo (blog tools, in mcp-admin-tools.service.ts),
• its name in the expected list in mcp-admin-tools.service.spec.ts, for any tool, and also in mcp-admin-ops-tools.service.spec.ts for an ops tool, plus that spec's writes map for an ops tool that writes.

See Admin MCP Server.

OpenAPI and type drift

These are verify stages. openapi.json and frontend/types/api.d.ts are generated, and verify regenerates both and diffs them against the committed files. Any change to a controller's decorators or a zod schema changes them, down to an @ApiOperation summary. Regenerate them; do not edit them by hand. See Troubleshooting.

What the test run found

Each failure message on this page was produced on 2026-10-25 in a fresh clone by making the change described next to it: a new AdminItemsController, a migration creating notes, a new admin_ping MCP tool, a .test.tsx file and a changed health-check summary. With Docker turned off, the backend's second jest pass printed the skip lines above.

Related

• Troubleshooting - each verify failure with its fix
• Adding a Module - the steps these specs check
• Home - Docs index