0
# Nx Jest Plugin
1

2
The Nx Jest Plugin provides comprehensive Jest testing capabilities for Nx monorepos, including test executors, configuration generators, and plugin infrastructure. It enables advanced features like affected testing, test parallelization, and intelligent caching within the Nx ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @nx/jest
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @nx/jest`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  configurationGenerator, 
16
  jestInitGenerator,
17
  addPropertyToJestConfig,
18
  removePropertyFromJestConfig,
19
  jestConfigObjectAst,
20
  getJestProjectsAsync
21
} from "@nx/jest";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  configurationGenerator, 
29
  jestInitGenerator,
30
  addPropertyToJestConfig,
31
  removePropertyFromJestConfig,
32
  jestConfigObjectAst,
33
  getJestProjectsAsync
34
} = require("@nx/jest");
35
```
36

37
Plugin and preset imports:
38

39
```typescript
40
import { createNodes, createNodesV2, JestPluginOptions } from "@nx/jest/plugin";
41
import { nxPreset } from "@nx/jest/preset";
42
```
43

44
## Basic Usage
45

46
```typescript
47
import { configurationGenerator, jestInitGenerator } from "@nx/jest";
48
import { Tree } from '@nx/devkit';
49

50
// Initialize Jest in workspace
51
await jestInitGenerator(tree, {
52
  skipFormat: false,
53
  addPlugin: true
54
});
55

56
// Add Jest configuration to specific project
57
await configurationGenerator(tree, {
58
  project: "my-project",
59
  testEnvironment: "jsdom",
60
  supportTsx: true
61
});
62
```
63

64
## Architecture
65

66
The Nx Jest Plugin is structured around several key components:
67

68
- **Executors**: Test runner implementation with batch execution support
69
- **Generators**: Project setup, initialization, and configuration tools  
70
- **Plugin System**: Nx plugin infrastructure for automatic project detection and configuration
71
- **Configuration Utilities**: Tools for programmatically managing Jest config files
72
- **Preset System**: Pre-configured Jest settings optimized for Nx workspaces
73

74
## Capabilities
75

76
### Test Execution
77

78
Jest test runner executor with support for batch execution, affected testing, and Nx-specific optimizations.
79

80
```typescript { .api }
81
interface JestExecutorOptions {
82
  codeCoverage?: boolean;
83
  config?: string;
84
  detectOpenHandles?: boolean;
85
  logHeapUsage?: boolean;
86
  detectLeaks?: boolean;
87
  jestConfig: string;
88
  testFile?: string;
89
  bail?: boolean | number;
90
  ci?: boolean;
91
  color?: boolean;
92
  clearCache?: boolean;
93
  findRelatedTests?: string;
94
  forceExit?: boolean;
95
  json?: boolean;
96
  maxWorkers?: number | string;
97
  onlyChanged?: boolean;
98
  changedSince?: string;
99
  outputFile?: string;
100
  passWithNoTests?: boolean;
101
  randomize?: boolean;
102
  runInBand?: boolean;
103
  showConfig?: boolean;
104
  silent?: boolean;
105
  testNamePattern?: string;
106
  testPathIgnorePatterns?: string[];
107
  testPathPatterns?: string[];
108
  colors?: boolean;
109
  reporters?: string[];
110
  verbose?: boolean;
111
  coverageReporters?: string[];
112
  coverageDirectory?: string;
113
  testResultsProcessor?: string;
114
  updateSnapshot?: boolean;
115
  useStderr?: boolean;
116
  watch?: boolean;
117
  watchAll?: boolean;
118
  testLocationInResults?: boolean;
119
  testTimeout?: number;
120
  setupFile?: string; // @deprecated
121
}
122
```
123

124
[Test Execution](./test-execution.md)
125

126
### Project Configuration
127

128
Generators for initializing Jest in workspaces and adding Jest configuration to individual projects.
129

130
```typescript { .api }
131
function configurationGenerator(
132
  tree: Tree, 
133
  options: JestProjectSchema
134
): Promise<GeneratorCallback>;
135

136
function jestInitGenerator(
137
  tree: Tree, 
138
  options: JestInitSchema
139
): Promise<GeneratorCallback>;
140

141
interface JestProjectSchema {
142
  project: string;
143
  targetName?: string;
144
  supportTsx?: boolean;
145
  setupFile?: 'angular' | 'web-components' | 'react-native' | 'react-router' | 'none';
146
  skipSerializers?: boolean;
147
  testEnvironment?: 'node' | 'jsdom' | 'none';
148
  skipFormat?: boolean;
149
  addPlugin?: boolean;
150
  compiler?: 'tsc' | 'babel' | 'swc';
151
  skipPackageJson?: boolean;
152
  js?: boolean;
153
  runtimeTsconfigFileName?: string;
154
  addExplicitTargets?: boolean;
155
  babelJest?: boolean; // @deprecated
156
  skipSetupFile?: boolean; // @deprecated
157
  keepExistingVersions?: boolean;
158
}
159

160
interface JestInitSchema {
161
  skipFormat?: boolean;
162
  skipPackageJson?: boolean;
163
  keepExistingVersions?: boolean;
164
  updatePackageScripts?: boolean;
165
  addPlugin?: boolean;
166
}
167
```
168

169
[Project Configuration](./project-configuration.md)
170

171
### Configuration Management
172

173
Utilities for programmatically modifying Jest configuration files with AST-based manipulation.
174

175
```typescript { .api }
176
function addPropertyToJestConfig(
177
  host: Tree,
178
  path: string,
179
  propertyName: string | string[],
180
  value: unknown,
181
  options?: { valueAsString: boolean }
182
): void;
183

184
function removePropertyFromJestConfig(
185
  host: Tree,
186
  path: string,
187
  propertyName: string | string[]
188
): void;
189

190
function jestConfigObjectAst(configString: string): ts.ObjectLiteralExpression;
191
```
192

193
[Configuration Management](./config-management.md)
194

195
### Plugin System
196

197
Nx plugin infrastructure for automatic Jest project detection and configuration inference.
198

199
```typescript { .api }
200
interface JestPluginOptions {
201
  targetName?: string;
202
  ciTargetName?: string;
203
  ciGroupName?: string;
204
  disableJestRuntime?: boolean;
205
}
206

207
function createNodes(
208
  configFilePath: string,
209
  options: JestPluginOptions | undefined,
210
  context: CreateNodesContext
211
): CreateNodesResult;
212

213
function createNodesV2(
214
  configFilePath: string,
215
  options: JestPluginOptions | undefined,
216
  context: CreateNodesContextV2
217
): Promise<CreateNodesResult>;
218
```
219

220
[Plugin System](./plugin-system.md)
221

222
### Multi-Project Support
223

224
Utilities for working with Jest multi-project configurations in Nx workspaces.
225

226
```typescript { .api }
227
function getJestProjectsAsync(): Promise<string[]>;
228
```
229

230
[Multi-Project Support](./multi-project.md)
231

232
### Preset Configuration
233

234
Pre-configured Jest settings optimized for Nx workspaces with TypeScript support.
235

236
```typescript { .api }
237
interface NxJestPreset {
238
  testMatch: string[];
239
  resolver: string;
240
  moduleFileExtensions: string[];
241
  coverageReporters: string[];
242
  transform: Record<string, [string, any]>;
243
  testEnvironment: string;
244
  testEnvironmentOptions: {
245
    customExportConditions: string[];
246
  };
247
}
248

249
const nxPreset: NxJestPreset;
250
```
251

252
[Preset Configuration](./preset-config.md)
253

254
## Types
255

256
### Core Type Definitions
257

258
```typescript { .api }
259
interface Tree {
260
  // Nx Tree interface for file system operations
261
}
262

263
interface GeneratorCallback {
264
  // Function returned by generators for post-execution tasks
265
  (): Promise<void> | void;
266
}
267

268
interface ExecutorContext {
269
  // Nx executor context with project and workspace information
270
}
271

272
interface CreateNodesContext {
273
  // Context for plugin node creation
274
}
275

276
interface CreateNodesContextV2 {
277
  // Enhanced context for plugin node creation v2
278
}
279

280
interface CreateNodesResult {
281
  // Result object for created plugin nodes
282
}
283

284
type NormalizedJestProjectSchema = JestProjectSchema & {
285
  rootProject: boolean;
286
  isTsSolutionSetup: boolean;
287
};
288
```