0
# Worker Process Management
1

2
Worker setup and execution functions for parallel test processing across multiple worker processes. This system enables Jest to run tests concurrently while maintaining isolation and providing efficient resource management.
3

4
## Capabilities
5

6
### Worker Setup Function
7

8
Initializes worker processes with serialized resolvers and module maps for efficient test execution.
9

10
```typescript { .api }
11
/**
12
 * Set up worker processes with necessary resolvers and module maps
13
 * Called once per worker process during initialization
14
 * @param setupData - Configuration data containing serializable resolvers
15
 */
16
export function setup(setupData: {
17
  serializableResolvers: Array<SerializableResolver>;
18
}): void;
19
```
20

21
**Usage Example:**
22

23
The `setup` function is internal to the jest-runner package and called automatically by the worker process management system. It is not part of the public API:
24

25
```typescript
26
// This is called internally by TestRunner when spawning workers
27
// Users do not need to call this directly
28
```
29

30
### Worker Execution Function
31

32
Executes individual tests within worker processes with proper context deserialization and error handling.
33

34
```typescript { .api }
35
/**
36
 * Execute a test within a worker process
37
 * @param workerData - Test execution data including config and context
38
 * @returns Promise resolving to test results
39
 */
40
export async function worker(workerData: {
41
  config: Config.ProjectConfig;
42
  globalConfig: Config.GlobalConfig;
43
  path: string;
44
  context: TestRunnerSerializedContext;
45
}): Promise<TestResult>;
46
```
47

48
**Usage Example:**
49

50
The `worker` function is internal to the jest-runner package and called automatically by the worker process management system. It is not part of the public API:
51

52
```typescript
53
// This is called internally by TestRunner via jest-worker
54
// Users do not need to call this directly
55
```
56

57
### Worker Process Architecture
58

59
The worker system is designed for efficient parallel test execution with proper isolation and resource management.
60

61
**Worker Lifecycle:**
62

63
1. **Process Creation**: `jest-worker` spawns worker processes
64
2. **Setup Phase**: `setup()` initializes resolvers and module maps
65
3. **Test Execution**: `worker()` processes individual test requests
66
4. **Communication**: Bidirectional messaging between main and worker processes
67
5. **Cleanup**: Graceful shutdown with resource deallocation
68

69
**Process Isolation:**
70
- Each worker runs in a separate Node.js process
71
- Independent module resolution and caching per worker
72
- Isolated global state and environment variables
73
- Memory usage tracking and limits per worker
74

75
### Resolver Management
76

77
Efficient resolver setup and caching for module resolution within worker processes.
78

79
```typescript { .api }
80
/**
81
 * Serializable resolver data for worker processes
82
 */
83
interface SerializableResolver {
84
  config: Config.ProjectConfig;
85
  serializableModuleMap: SerializableModuleMap;
86
}
87
```
88

89
**Resolver Caching:**
90
The `setup` function creates and caches resolvers for each project configuration:
91

92
```typescript
93
// Internal resolver caching (not exported)
94
const resolvers = new Map<string, Resolver>();
95

96
// Resolver creation from serialized module maps
97
for (const { config, serializableModuleMap } of setupData.serializableResolvers) {
98
  const moduleMap = HasteMap.getStatic(config).getModuleMapFromJSON(serializableModuleMap);
99
  resolvers.set(config.id, Runtime.createResolver(config, moduleMap));
100
}
101
```
102

103
### Context Serialization
104

105
Proper serialization and deserialization of test runner context for worker communication.
106

107
```typescript { .api }
108
/**
109
 * Serialized version of TestRunnerContext for worker processes
110
 * Converts Sets to Arrays for JSON serialization
111
 */
112
interface TestRunnerSerializedContext {
113
  changedFiles?: Array<string>;
114
  sourcesRelatedToTestsInChangedFiles?: Array<string>;
115
}
116

117
/**
118
 * Serialized setup data passed to worker processes during initialization
119
 */
120
interface SerializableResolver {
121
  config: Config.ProjectConfig;
122
  serializableModuleMap: SerializableModuleMap;
123
}
124
```
125

126
**Context Conversion:**
127
The worker function converts serialized arrays back to Sets:
128

129
```typescript
130
// Convert serialized context back to Sets
131
const context: TestRunnerContext = {
132
  ...workerData.context,
133
  changedFiles: workerData.context.changedFiles && new Set(workerData.context.changedFiles),
134
  sourcesRelatedToTestsInChangedFiles: workerData.context.sourcesRelatedToTestsInChangedFiles &&
135
    new Set(workerData.context.sourcesRelatedToTestsInChangedFiles)
136
};
137
```
138

139
### Error Handling and Communication
140

141
Robust error handling with proper serialization for cross-process communication.
142

143
**Error Formatting:**
144
```typescript { .api }
145
interface SerializableError {
146
  code?: string;
147
  message: string;
148
  stack?: string;
149
  type: string;
150
}
151

152
/**
153
 * Format errors for serialization across process boundaries
154
 */
155
const formatError = (error: string | ErrorWithCode): SerializableError => {
156
  if (typeof error === 'string') {
157
    const { message, stack } = separateMessageFromStack(error);
158
    return { message, stack, type: 'Error' };
159
  }
160
  
161
  return {
162
    code: error.code || undefined,
163
    message: error.message,
164
    stack: error.stack,
165
    type: 'Error'
166
  };
167
};
168
```
169

170
**Uncaught Exception Handling:**
171
Workers install global error handlers to prevent crashes:
172

173
```typescript
174
process.on('uncaughtException', err => {
175
  if (err.stack) {
176
    console.error(err.stack);
177
  } else {
178
    console.error(err);
179
  }
180
  exit(1); // Uses exit-x for proper cleanup
181
});
182
```
183

184
### Worker Communication Protocol
185

186
The worker system uses `jest-worker`'s messaging system for communication between main and worker processes.
187

188
**Message Flow:**
189

190
1. **Main → Worker**: Test execution requests with serialized data
191
2. **Worker → Main**: Real-time events during test execution
192
3. **Worker → Main**: Final test results or error information
193
4. **Main ↔ Worker**: Bidirectional custom message handling
194

195
**Event Forwarding:**
196
Workers can send events back to the main process during test execution:
197

198
```typescript
199
// Send events from worker to main process
200
const sendMessageToJest: TestFileEvent = (eventName, args) => {
201
  messageParent([eventName, args]);
202
};
203

204
// Events are forwarded through the communication channel
205
await runTest(path, globalConfig, config, resolver, context, sendMessageToJest);
206
```
207

208
### Worker Configuration Options
209

210
Workers support various configuration options for optimal performance and resource management.
211

212
**Worker Creation Options:**
213
- `enableWorkerThreads`: Use worker threads instead of child processes
214
- `exposedMethods`: Methods available for calling from main process
215
- `forkOptions`: Node.js child process options including serialization mode
216
- `idleMemoryLimit`: Memory limit for idle workers
217
- `maxRetries`: Maximum retry attempts for failed operations
218
- `numWorkers`: Number of worker processes to spawn
219
- `setupArgs`: Arguments passed to setup function
220

221
**Memory Management:**
222
Workers can be configured with memory limits and monitoring:
223

224
```typescript
225
// Worker memory limit configuration
226
idleMemoryLimit: typeof globalConfig.workerIdleMemoryLimit === 'number'
227
  ? globalConfig.workerIdleMemoryLimit
228
  : undefined
229
```
230

231
### Process Cleanup and Shutdown
232

233
Proper cleanup procedures ensure workers shut down gracefully without resource leaks.
234

235
**Graceful Shutdown:**
236
- Workers respond to shutdown signals from main process
237
- Resources are properly deallocated before process termination
238
- Force-exit detection and warning for stuck processes
239

240
**Resource Management:**
241
- Module caches are cleared on shutdown
242
- File handles and network connections are closed
243
- Memory is released through garbage collection
244

245
## Types
246

247
```typescript { .api }
248
interface WorkerData {
249
  config: Config.ProjectConfig;
250
  globalConfig: Config.GlobalConfig;
251
  path: string;
252
  context: TestRunnerSerializedContext;
253
}
254

255
interface SerializableModuleMap {
256
  duplicates: ReadonlyMap<string, DuplicatesSet>;
257
  map: ReadonlyMap<string, ModuleMapItem>;
258
  mocks: ReadonlyMap<string, string>;
259
  rootDir: string;
260
}
261

262
interface ModuleMapItem {
263
  [platform: string]: ModuleMapData;
264
}
265

266
interface ModuleMapData {
267
  [key: string]: string;
268
}
269

270
interface DuplicatesSet {
271
  [key: string]: {[key: string]: number};
272
}
273

274
interface ErrorWithCode extends Error {
275
  code?: string;
276
}
277

278
type TestFileEvent = (
279
  eventName: string,
280
  args: Array<any>
281
) => void | Promise<void>;
282
```