fog/.agents/skills/nx-import/references/JEST.md

Jest

Jest-specific guidance for nx import. For the basic "Jest Preset Missing" fix (create jest.preset.js, install deps), see SKILL.md. This file covers deeper Jest integration issues.

---

How @nx/jest Works

@nx/jest/plugin scans for jest.config.{ts,js,cjs,mjs,cts,mts} and creates a test target for each project.

Plugin options:

{
  "plugin": "@nx/jest/plugin",
  "options": {
    "targetName": "test"
  }
}

npx nx add @nx/jest does two things:

1. Registers @nx/jest/plugin in nx.json — without this, no test targets are inferred
2. Updates namedInputs.production to exclude test files

Gotcha: nx add @nx/jest does NOT create jest.preset.js — that file is only generated when you run a generator (e.g. @nx/jest:configuration). For imports, you must create it manually (see "Jest Preset" section below).

Other gotcha: If you create jest.preset.js manually but skip npx nx add @nx/jest, the plugin won't be registered and nx run PROJECT:test will fail with "Cannot find target 'test'". You need both.

---

Jest Preset

The preset provides shared Jest configuration (test patterns, ts-jest transform, resolver, jsdom environment).

Root jest.preset.js:

const nxPreset = require('@nx/jest/preset').default;
module.exports = { ...nxPreset };

Project jest.config.ts:

export default {
  displayName: 'my-lib',
  preset: '../../jest.preset.js',
  // project-specific overrides
};

The preset path is relative from the project root to the workspace root. Subdirectory imports preserve the original relative path (e.g. ../../jest.preset.js), which resolves correctly if the import destination matches the source directory depth.

---

Testing Dependencies

Core (always needed)

pnpm add -wD jest ts-jest @types/jest @nx/jest

Environment-specific

• DOM testing (React, Vue, browser libs): jest-environment-jsdom
• Node testing (APIs, CLIs): no extra deps (Jest defaults to node env, but Nx preset defaults to jsdom)

React testing

pnpm add -wD @testing-library/react @testing-library/jest-dom

React with Babel (non-ts-jest transform)

Some React projects use Babel instead of ts-jest for JSX transformation:

pnpm add -wD babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript

When: Project jest.config has transform using babel-jest instead of ts-jest. Common in older Nx workspaces and CRA migrations.

Vue testing

pnpm add -wD @vue/test-utils

Vue projects typically use Vitest (not Jest) — see VITE.md.

---

tsconfig.spec.json

Jest projects need a tsconfig.spec.json that includes test files:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "module": "commonjs",
    "types": ["jest", "node"]
  },
  "include": ["jest.config.ts", "src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"]
}

Common issues after import:

• Missing "types": ["jest", "node"] — causes describe/it/expect to be unrecognized
• Missing "module": "commonjs" — Jest doesn't support ESM by default (ts-jest transpiles to CJS)
• include array missing test patterns — TypeScript won't check test files

---

Jest vs Vitest Coexistence

Workspaces can have both:

• Jest: Next.js apps, older React libs, Node libraries
• Vitest: Vite-based React/Vue apps and libs

Both @nx/jest/plugin and @nx/vite/plugin (which infers Vitest targets) coexist without conflicts — they detect different config files (jest.config.* vs vite.config.*).

Target naming: Both default to test. If a project somehow has both config files, rename one:

{
  "plugin": "@nx/jest/plugin",
  "options": { "targetName": "jest-test" }
}

---

@testing-library/jest-dom — Jest vs Vitest

Projects migrating from Jest to Vitest (or workspaces with both) need different imports:

Jest (in test-setup.ts):

import '@testing-library/jest-dom';

Vitest (in test-setup.ts):

import '@testing-library/jest-dom/vitest';

If the source used Jest but the dest workspace uses Vitest for that project type, update the import path. Also add @testing-library/jest-dom to tsconfig types array.

---

Non-Nx Source: Test Script Rewriting

Nx rewrites package.json scripts during init. Test scripts get broken:

• "test": "jest" → "test": "nx test" (circular if no executor configured)
• "test": "vitest run" → "test": "nx test run" (broken — run becomes an argument)

Fix: Remove all rewritten test scripts. @nx/jest/plugin and @nx/vite/plugin infer test targets from config files.

---

CI Atomization

@nx/jest/plugin supports splitting tests per-file for CI parallelism:

{
  "plugin": "@nx/jest/plugin",
  "options": {
    "targetName": "test",
    "ciTargetName": "test-ci"
  }
}

This creates test-ci--src/lib/foo.spec.ts targets for each test file, enabling Nx Cloud distribution. Not relevant during import, but useful for post-import CI setup.

---

Common Post-Import Issues

1. "Cannot find target 'test'": @nx/jest/plugin not registered in nx.json. Run npx nx add @nx/jest or manually add the plugin entry.

2. "Cannot find module 'jest-preset'": jest.preset.js missing at workspace root. Create it (see SKILL.md).

3. "Cannot find type definition file for 'jest'": Missing @types/jest or tsconfig.spec.json doesn't have "types": ["jest", "node"].

4. Tests fail with "Cannot use import statement outside a module": ts-jest not installed or not configured as transform. Check jest.config.ts transform section.

5. Snapshot path mismatches: After import, __snapshots__ directories may have paths baked in. Run tests once with --updateSnapshot to regenerate.

---

Fix Order

Subdirectory Import (Nx Source)

1. npx nx add @nx/jest — registers plugin in nx.json (does NOT create jest.preset.js)
2. Create jest.preset.js manually (see "Jest Preset" section above)
3. Install deps: pnpm add -wD jest jest-environment-jsdom ts-jest @types/jest
4. Install framework test deps: @testing-library/react @testing-library/jest-dom (React), @vue/test-utils (Vue)
5. Verify tsconfig.spec.json has "types": ["jest", "node"]
6. nx run-many -t test

Whole-Repo Import (Non-Nx Source)

1. Remove rewritten test scripts from package.json
2. npx nx add @nx/jest — registers plugin (does NOT create preset)
3. Create jest.preset.js manually
4. Install deps (same as above)
5. Verify/fix jest.config.* — ensure preset path points to root jest.preset.js
6. Verify/fix tsconfig.spec.json — add types, module, include if missing
7. nx run-many -t test