Test file naming: *.test vs *.spec
0002. Test file naming: *.test vs *.spec
Section titled “0002. Test file naming: *.test vs *.spec”- Status: accepted
- Date: 2026-07-17
- Deciders: FRAME maintainers
Context
Section titled “Context”Nest scaffolding and many tutorials default to colocated *.spec.ts for unit tests, while Playwright commonly uses *.spec.ts for browser e2e. Mixing both layers under one suffix makes it easy for agents (and humans) to put HTTP/browser suites next to units, or to invent a third suffix (*.e2e-spec.ts).
Options considered:
- Nest-style: unit and Nest e2e both
*.spec.ts(layer only by folder). - Vitest-style: everything
*.test.ts. - Split by layer: unit
*.test.ts(x), integration/e2e*.spec.tsundere2e/orintegration/— drop*.e2e-spec.ts.
Decision
Section titled “Decision”Use option 3 repo-wide:
| Suffix | Layer | Placement |
|---|---|---|
*.test.ts(x) | Unit | Colocated next to the module |
*.spec.ts | Integration / e2e | Under e2e/ or integration/ |
Enforcement: @frame/vitest unit configs include only **/*.test.ts(x); Nest e2e uses e2e/**/*.spec.ts; Next Playwright uses testMatch: '**/*.spec.ts'.
Consequences
Section titled “Consequences”- Positive: Filename signals test layer; Nest training data that suggests
*.spec.tsfor units is overridden by AGENTS/skills/configs. - Negative / trade-offs: Nest generators may still emit
*.spec.ts— rename to*.test.tsfor units. - Follow-ups: Keep oxlint Vitest vs Playwright globs aligned with this split.
- Related skills / AGENTS: root
AGENTS.md(Testing),.agents/skills/vitest-testing,apps/nest/AGENTS.md,apps/next/AGENTS.md - Starlight guide: Testing principles