Test Conventions
Every project names and places its tests the same way, so a single glob recognises a test file in every tool: Vitest and Playwright configs, tsconfigs, Nx inputs, knip and release locks.
Suffixes
| Suite | Suffix | Example |
|---|---|---|
| Unit | *.spec.ts/.spec.tsx | __tests__/lib/repair.spec.ts |
| Integration | *.integration.spec.ts | __tests__/repository.integration.spec.ts |
| End-to-end | *.e2e.spec.ts | src/diary-flow.e2e.spec.ts (e2e project) |
| Plain JS | *.spec.mjs | __tests__/release/install.spec.mjs |
Never use *.test.*. The kind marker (integration, e2e) lets a project run slow suites as separate targets by include glob.
Placement
Tests live in the project's root __tests__/ folder, which mirrors src/:
libs/json-repair/
├── src/lib/json-repair.ts
└── __tests__/lib/json-repair.spec.tsTest support code goes in __tests__/ too: setup files, fixtures, fakes, harnesses and shared helpers. src/ holds production code only, so the __tests__/** glob is the whole boundary between production and test code. Nx production inputs, tsconfig.lib.json and published files exclude it without per-file rules.
*-e2e projects contain only tests and keep them in src/.
libs/cpp-sdk follows CMake conventions and is exempt.
Enforcement
pnpm run check:test-conventions (tools/src/check-test-conventions.ts) runs in CI and fails on:
- a
*.test.*file, or a legacy*.e2e.tsfile; - a test file outside the project-root
__tests__/folder (non-e2e projects); - another test folder, such as
tests/or a nested__tests__/; - a file in
src/that imports a test framework (vitest,@testing-library/*,@playwright/test,node:test).
Migrating a project
The harmonize-tests generator renames and moves a project's tests, moves its test support files, rewrites relative imports, vi.mock paths and import.meta.url paths, and updates the project's config globs:
pnpm exec nx g @moltnet/tools:harmonize-tests --project=<name> --dry-run
pnpm exec nx g @moltnet/tools:harmonize-tests --project=<name>It prints the path expressions it cannot rewrite statically, such as a path computed from import.meta.dirname at runtime. Fix those by hand, then check that the project's test target collects the same files as before.