Fast gates
pnpm install --frozen-lockfile
pnpm check-types
pnpm lint
pnpm i18n:check
pnpm exec oxlint
FORMAT_BASE_REF=origin/main pnpm format:check
pnpm test
pnpm --filter mobile exec tsc --noEmitType checks do not validate Worker bundling or database behavior. The format check compares changed files to its base reference; use the intended review base.
Isolated Postgres
node scripts/test-local-postgres.mjs exec pnpm test:integration
node scripts/test-local-postgres.mjs exec node scripts/test-local-jobs.mjsThe wrapper creates a disposable local cluster, exports the owned test database variables, applies migrations and stops its cluster when the child finishes. It refuses unsafe assumptions about a remote/shared test database. The jobs harness runs the built Worker with controlled provider fixtures and exercises persisted outcomes, timeouts, leases and repeated ticks.
Effect timeout unit tests use @effect/vitest with TestClock and production durations. Queue persistence changes additionally require the fault gate in ADR-0006.
What to test
Test the decisions your change makes, not the framework, the ORM or a getter. Database tests run against the disposable cluster above.
Every procedure:
- one success with the documented output;
- one
INPUT_VALIDATIONrejection (HTTP 400 on the wire;BAD_REQUESTthrough an in-processcreateRouterClient); - a caller who is not a Member of the Active Organization gets
FORBIDDEN; - another Organization's row is a
NOT_FOUND, never a result (use thetwo-tenantsfixture inpackages/api/src/testing/two-tenants.ts); - each tagged error the service can raise, asserting the code and message the client sees (the pilots pin theirs through the real RPC handler in
packages/api/src/testing/characterization/); - an audited write records its Audit Event in the same transaction.
Every new table or tenant path: the RLS catalog test passes, and the change is proved on every role profile with pnpm --filter @template-cloudflare/db test:rls-matrix.
Every job: a replay of the same work is a no-op, a lease held by another consumer is not overwritten, and a deadline uses the production value with TestClock.
Every list: the order is stable with equal sort values, the limit is capped, and a malformed cursor is rejected as input.
Built Worker
pnpm --filter web build
# Run from apps/web in an isolated local test environment:
pnpm exec wrangler dev -c dist/server/wrangler.json --local --port 8790 \
--local-upstream localhost:8790--local-upstream keeps request.url on localhost. Without it, the production route in the built config becomes the request host, and URLs the Worker mints (files upload targets, og:image) point at the live site.
Provide the Hyperdrive local override for the configured binding ID with a password-bearing URL such as postgresql://template_owner:[email protected]:PORT/template_test (the table owner pnpm test:integration creates). The exact variable name comes from the Wrangler binding. Keep local tests local; do not deploy to discover a bundling failure.
The build checks that client assets contain no server-only markers and that production AI code does not gain the server-function manifest dependency. Runtime smoke checks should include a public page, the changed API, auth refusal paths and discovery endpoints.
End-to-end
pnpm test:e2e builds the Worker and runs the web suite in apps/e2e on one locked local stack; the mobile suite drives the iOS development build. Setup, the lock, the cleanup guarantees and the model for agent steps: End-to-end tests.
Docs checks
The web unit suite loads compiled MDX, validates metadata and links, orders releases, and checks Markdown/discovery output. It runs on Node, so it cannot see which fumadocs-core/server entry the Worker bundles: pnpm --filter web build runs assert-docs-renderer.mjs, which fails when the browser entry (it only throws) reaches dist/server. Browser review covers light/dark, desktop/mobile, keyboard focus, local diagram scrolling, code blocks and the command palette. Bundle reports separate total client assets from the initial route graph.