Test layout
Tests live in a test/ tree beside src/, never inside src/. Inside test/, the first level is
the layer (what a test needs to run). Below that, paths mirror src/, so the tests for
src/secrets/service.ts are at test/<layer>/secrets/service.test.ts. One source module can have
tests in several layers.
<package>/ src/secrets/service.ts test/ support/ shared test infrastructure, never contains tests unit/<mirror of src>/ *.test.ts integration/<mirror of src>/ *.test.ts api/<mirror of src>/ *.test.ts (server only)- Pick the lowest layer that can prove the behavior. A function with no I/O is a unit test, even if it lives in a feature folder.
- Mirror the source path. Name the file after the module it tests:
src/crypto/keyring.ts→test/unit/crypto/keyring.test.ts. A test that spans a whole feature is named after the feature (test/api/secrets/secrets.test.ts). App-wide behaviors (error contract, leak canaries, health) sit at the top of their layer (test/api/no-leak.test.ts). - Shared helpers go in
test/support/, split by concern, never in one growing file. Import them through the support entry point (#test/supporton the server). A new domain addssupport/factories/<domain>.tsand re-exports it fromsupport/index.ts. - Import source through
#src/...on the server (Node subpath imports inapps/server/package.json), not through../../../src. Moving a test file never breaks its imports. - Every layer has its own script:
pnpm testruns all layers;test:<layer>runs one. - One test file per migration:
migrations/0002_access.sql→test/integration/db/migration-0002.test.ts. - A new table needs a
resetDbentry.test/support/db.tslists every table child-first;test/integration/db/reset.test.tsfails when a migration adds a table that is not listed.
Layers per package
Section titled “Layers per package”| Package | Layer | Contains | Runs in |
|---|---|---|---|
apps/server |
unit/ |
pure logic: crypto, encoding, lockout, policy, log redaction | workerd |
integration/ |
services and repos against a real local D1; schema and migrations | workerd + D1 | |
api/ |
HTTP through the Worker’s fetch handler: status codes, auth, CSRF, error bodies | workerd + D1 | |
packages/shared |
unit/ is implicit: tests sit directly under test/<mirror> |
schemas, pure helpers | Node |
apps/cli |
unit/ |
output formatting, config parsing, env-file rendering | Node |
integration/ |
commands run through runCli with fake API, prompts, spawner, temp dirs |
Node | |
e2e/ |
the built CLI against a real local server (vitest.e2e.config.ts) |
Node + workerd | |
apps/web |
unit/ |
src/lib helpers, query keys, formatting |
jsdom |
components/ |
src/components rendered with Testing Library |
jsdom | |
routes/ |
src/routes screens with MSW handlers |
jsdom + MSW | |
features/ |
src/features/<feature> modules (screens, hooks) with MSW handlers |
jsdom + MSW | |
e2e/ |
Playwright smoke against wrangler dev (*.spec.ts) |
browser |
packages/shared is small and has no I/O, so it skips the layer level: src/schemas/secrets.ts →
test/schemas/secrets.test.ts. Add a layer level if it ever gains a test that needs more than Node.
Source layout that keeps this scalable
Section titled “Source layout that keeps this scalable”- Server: one folder per feature under
src/(auth/,projects/,secrets/, latermembers/,audit/, …), each withroutes.ts,service.tsandrepo.tsas needed. Shared infrastructure stays insrc/lib/andsrc/crypto/. - Shared: schemas are split by domain under
src/schemas/<domain>.tsand re-exported fromsrc/schemas/index.ts. A new domain adds a file; it does not grow an existing one.