fog/docs/adr/0003-mixed-test-runners.md

0003 — Vitest in libs and overlay, Jest in API

• Status: Accepted
• Date: 2026-05-06

Context and problem statement

The Nx workspace contains an Angular frontend, a NestJS backend, and three TypeScript libraries. Each subsystem has different test runner support in current Nx generators. Should the workspace standardise on a single runner, accept mixed runners, or prioritise tooling alignment over uniformity?

Decision drivers

• Generator support. Forcing a non-default runner means working against the grain of the Nx generator and maintaining custom configuration.
• Speed. Vitest is meaningfully faster than Jest for monorepo work.
• Ecosystem fit. Angular 21 made Vitest the official default. NestJS examples and community resources still assume Jest.
• Test isolation. API tests and frontend tests rarely run in the same breath; the cost of a mixed setup is mostly cognitive, not operational.
• Future migration cost. If we standardise wrong now, the cost of switching later is non-trivial — Jest and Vitest mock semantics differ subtly.

Considered options

1. Jest everywhere. Use the API's default and force Jest into the libs and overlay.
2. Vitest everywhere. Force Vitest into the API by manually configuring it after the Nx Nest generator runs.
3. Mixed: Vitest in libs and overlay, Jest in API. Use each subsystem's native default.
4. Vitest in shared libs, Jest in both apps. Compromise position.

Decision outcome

Chosen: Mixed — Vitest in libs and overlay, Jest in API.

The Nx Nest generator (@nx/nest:application) only supports jest and none for its unitTestRunner option in the version we're using. The Angular generator (@nx/angular:application) supports vitest-angular (the official Angular Vitest integration) and uses it as the default. The plain JS library generator (@nx/js:library) supports both; we chose Vitest there for consistency with the overlay.

Working with the generator defaults avoids fighting the tooling. The cost — two test runners in one workspace — is small in practice because:

• Nx's run-many --target=test runs both transparently.
• Property-based tests (fast-check) work identically in both.
• Mock semantics differ slightly, but the differences only matter at the test author level, and shared libs use one runner consistently.

Consequences

Positive

• Each generator runs cleanly with default flags — minimal custom configuration.
• Vitest gives us fast feedback on the overlay and shared libs (the parts most under iteration).
• Jest gives us battle-tested Nest testing utilities (Test.createTestingModule, getRepositoryToken, etc.) without translation.
• When @nx/nest adds first-class Vitest support (likely a future Nx version), migration is contained to one project.

Negative

• Two sets of test config files (jest.config.cts for API, vitest.config.mts for libs and overlay).
• Onboarding requires explaining the split.
• A test utility that targets one runner can't be trivially shared to projects using the other.

Neutral

• This decision should be revisited when @nx/nest ships native Vitest support, or when the Nest community shifts decisively to Vitest. Track in PROJECT_CONTEXT.md "Open decisions" section.