0
# Test Execution
1

2
Jest test runner executor with support for batch execution, affected testing, and Nx-specific optimizations. The executor provides comprehensive test execution capabilities including coverage reporting, watch mode, and integration with Nx's caching and parallelization features.
3

4
## Capabilities
5

6
### Jest Executor
7

8
Main Jest test runner executor with comprehensive configuration options and batch execution support.
9

10
```typescript { .api }
11
/**
12
 * Jest test executor with Nx-specific optimizations
13
 * @param options - Jest execution options
14
 * @param context - Nx executor context
15
 * @returns Promise resolving to execution result
16
 */
17
function jestExecutor(
18
  options: JestExecutorOptions,
19
  context: ExecutorContext
20
): Promise<{ success: boolean }>;
21

22
/**
23
 * Batch Jest executor for running multiple Jest projects in parallel
24
 * @param taskGraph - Graph of tasks to execute
25
 * @param inputs - Map of project names to Jest executor options
26
 * @param overrides - Global Jest executor options to apply to all projects
27
 * @param context - Nx executor context
28
 * @returns Promise resolving to batch execution results
29
 */
30
function batchJest(
31
  taskGraph: TaskGraph,
32
  inputs: Record<string, JestExecutorOptions>,
33
  overrides: JestExecutorOptions,
34
  context: ExecutorContext
35
): Promise<BatchResults>;
36
```
37

38
### Jest Executor Options
39

40
Complete configuration interface for Jest test execution.
41

42
```typescript { .api }
43
interface JestExecutorOptions {
44
  /** Enable code coverage collection and reporting */
45
  codeCoverage?: boolean;
46
  /** Path to Jest configuration file */
47
  config?: string;
48
  /** Detect handles that prevent Jest from exiting cleanly */
49
  detectOpenHandles?: boolean;
50
  /** Track and log memory usage */
51
  logHeapUsage?: boolean;
52
  /** Detect memory leaks in tests */
53
  detectLeaks?: boolean;
54
  /** Path to Jest configuration file (required) */
55
  jestConfig: string;
56
  /** Run specific test file */
57
  testFile?: string;
58
  /** Stop after first test failure or N failures */
59
  bail?: boolean | number;
60
  /** Run in continuous integration mode */
61
  ci?: boolean;
62
  /** Force color output */
63
  color?: boolean;
64
  /** Delete Jest cache directory before running tests */
65
  clearCache?: boolean;
66
  /** Find and run tests related to changed files */
67
  findRelatedTests?: string;
68
  /** Force Jest to exit after tests complete */
69
  forceExit?: boolean;
70
  /** Print test results in JSON format */
71
  json?: boolean;
72
  /** Maximum number of worker processes */
73
  maxWorkers?: number | string;
74
  /** Run tests only for changed files */
75
  onlyChanged?: boolean;
76
  /** Run tests for files changed since specified commit */
77
  changedSince?: string;
78
  /** Write test results to specified file */
79
  outputFile?: string;
80
  /** Allow empty test suites to pass */
81
  passWithNoTests?: boolean;
82
  /** Randomize test execution order */
83
  randomize?: boolean;
84
  /** Run tests serially in current process */
85
  runInBand?: boolean;
86
  /** Print Jest configuration and exit */
87
  showConfig?: boolean;
88
  /** Suppress output except for errors */
89
  silent?: boolean;
90
  /** Run tests matching specified name pattern */
91
  testNamePattern?: string;
92
  /** Ignore tests matching these patterns */
93
  testPathIgnorePatterns?: string[];
94
  /** Run tests matching these patterns */
95
  testPathPatterns?: string[];
96
  /** Enable colored output */
97
  colors?: boolean;
98
  /** List of test reporters to use */
99
  reporters?: string[];
100
  /** Enable verbose output */
101
  verbose?: boolean;
102
  /** List of coverage reporters to use */
103
  coverageReporters?: string[];
104
  /** Directory for coverage reports */
105
  coverageDirectory?: string;
106
  /** Custom test results processor */
107
  testResultsProcessor?: string;
108
  /** Update snapshots during test run */
109
  updateSnapshot?: boolean;
110
  /** Use stderr for output instead of stdout */
111
  useStderr?: boolean;
112
  /** Watch files for changes and rerun tests */
113
  watch?: boolean;
114
  /** Watch all files for changes */
115
  watchAll?: boolean;
116
  /** Include location information in test results */
117
  testLocationInResults?: boolean;
118
  /** Global test timeout in milliseconds */
119
  testTimeout?: number;
120
  /** 
121
   * Setup file configuration
122
   * @deprecated Use the setupFilesAfterEnv option in Jest configuration instead
123
   */
124
  setupFile?: string;
125
}
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
import { jestExecutor } from "@nx/jest";
132
import { ExecutorContext } from '@nx/devkit';
133

134
// Basic test execution
135
const result = await jestExecutor({
136
  jestConfig: "./jest.config.ts",
137
  codeCoverage: true
138
}, context);
139

140
// Advanced configuration with specific options
141
const advancedResult = await jestExecutor({
142
  jestConfig: "./jest.config.ts",
143
  codeCoverage: true,
144
  testEnvironment: "jsdom",
145
  maxWorkers: 4,
146
  bail: 1,
147
  verbose: true,
148
  coverageReporters: ["html", "lcov", "text-summary"],
149
  testPathPatterns: ["**/*.spec.ts"]
150
}, context);
151

152
// Running specific test file
153
const specificTest = await jestExecutor({
154
  jestConfig: "./jest.config.ts",
155
  testFile: "src/app/component.spec.ts"
156
}, context);
157
```
158

159
### Executor Configuration
160

161
The Jest executor is configured in the project's `project.json` or `workspace.json`:
162

163
```json
164
{
165
  "targets": {
166
    "test": {
167
      "executor": "@nx/jest:jest",
168
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
169
      "options": {
170
        "jestConfig": "apps/my-app/jest.config.ts",
171
        "passWithNoTests": true
172
      },
173
      "configurations": {
174
        "ci": {
175
          "ci": true,
176
          "codeCoverage": true
177
        }
178
      }
179
    }
180
  }
181
}
182
```
183

184
### Batch Execution
185

186
For running multiple Jest projects in parallel:
187

188
```typescript
189
import { batchJest } from "@nx/jest";
190

191
// Batch execution automatically handles parallelization
192
// and is used internally by Nx when running multiple projects
193
const batchResults = await batchJest(
194
  taskGraph,
195
  {
196
    "project1": { jestConfig: "./apps/project1/jest.config.ts" },
197
    "project2": { jestConfig: "./apps/project2/jest.config.ts" }
198
  },
199
  { ci: true }, // Global overrides applied to all projects
200
  context
201
);
202
```
203

204
### Task Graph Integration
205

206
```typescript { .api }
207
interface TaskGraph {
208
  // Graph structure for task dependencies and execution order
209
}
210

211
interface BatchResults {
212
  // Results from batch execution of multiple tasks
213
}
214
```