0
# Parallel Test Execution
1

2
The `ParallelRunner` class provides high-performance parallel test execution by distributing specs across multiple worker processes with automatic load balancing and result aggregation.
3

4
## Capabilities
5

6
### ParallelRunner Class
7

8
Parallel test runner distributing specs across multiple worker processes for faster execution.
9

10
```javascript { .api }
11
/**
12
 * Configures, builds, and executes a Jasmine test suite in parallel
13
 * @param options - Configuration options for the parallel runner
14
 */
15
class ParallelRunner {
16
  constructor(options?: ParallelRunnerOptions);
17
  
18
  /** Whether to cause the Node process to exit when the suite finishes executing */
19
  exitOnCompletion: boolean;
20
}
21

22
interface ParallelRunnerOptions {
23
  /** The path to the project's base directory */
24
  projectBaseDir?: string;
25
  /** The number of worker processes to use */
26
  numWorkers?: number;
27
  /** Whether to create the globals (describe, it, etc) that make up Jasmine's spec-writing interface */
28
  globals?: boolean;
29
}
30
```
31

32
### Parallel Test Execution
33

34
Execute tests across multiple worker processes with automatic spec distribution and result aggregation.
35

36
```javascript { .api }
37
/**
38
 * Runs the test suite in parallel across multiple workers
39
 * @param files - Spec files to run instead of the previously configured set
40
 * @param filterString - Regex used to filter specs (objects not supported in parallel mode)
41
 * @returns Promise that resolves when the suite completes
42
 */
43
execute(files?: string[], filterString?: string): Promise<JasmineDoneInfo>;
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
const ParallelRunner = require('jasmine/parallel');
50

51
// Basic parallel execution
52
const runner = new ParallelRunner({ numWorkers: 4 });
53
await runner.loadConfigFile();
54
await runner.execute();
55

56
// Run specific files in parallel
57
await runner.execute(['spec/unit/**/*.js', 'spec/integration/**/*.js']);
58

59
// Filter specs with regex (string only in parallel mode)
60
await runner.execute(null, 'integration');
61

62
// Auto-detect worker count
63
const autoRunner = new ParallelRunner({ numWorkers: require('os').cpus().length - 1 });
64
await autoRunner.execute();
65
```
66

67
### Worker Management
68

69
Control the number of worker processes and parallel execution behavior.
70

71
```javascript { .api }
72
/**
73
 * Sets whether to randomize the order of specs
74
 * Note: Randomization cannot be disabled in parallel mode
75
 * @param value - Must be true, throws error if false
76
 */
77
randomizeTests(value: boolean): void;
78

79
/**
80
 * Sets the random seed
81
 * Note: Random seed cannot be set in parallel mode
82
 * @param seed - Not supported, throws error
83
 */
84
seed(seed: string): void;
85
```
86

87
**Important Notes:**
88

89
- Parallel mode always randomizes specs and cannot disable randomization
90
- Random seeds cannot be set in parallel mode for reproducible runs
91
- Specs are automatically distributed across workers with load balancing
92

93
### Parallel Reporter Management
94

95
Add and manage reporters that support parallel execution with proper capability validation.
96

97
```javascript { .api }
98
/**
99
 * Add a custom reporter to the parallel runner
100
 * @param reporter - The reporter to add (must support parallel mode)
101
 * @param errorContext - Optional context for error messages
102
 */
103
addReporter(reporter: ParallelReporter, errorContext?: string): void;
104

105
/**
106
 * Clears all registered reporters
107
 */
108
clearReporters(): void;
109

110
interface ParallelReporter extends Reporter {
111
  /** Required capability declaration for parallel support */
112
  reporterCapabilities: {
113
    parallel: true;
114
  };
115
}
116
```
117

118
**Usage Example:**
119

120
```javascript
121
const ParallelRunner = require('jasmine/parallel');
122

123
const customReporter = {
124
  reporterCapabilities: { parallel: true },
125
  jasmineStarted: (options) => {
126
    console.log(`Starting parallel execution with ${options.numWorkers} workers`);
127
  },
128
  jasmineDone: (result) => {
129
    console.log(`Parallel execution completed in ${result.totalTime}ms using ${result.numWorkers} workers`);
130
  },
131
  specDone: (result) => {
132
    // This will be called from all workers
133
    console.log(`Spec completed: ${result.description}`);
134
  }
135
};
136

137
const runner = new ParallelRunner({ numWorkers: 3 });
138
runner.addReporter(customReporter);
139
await runner.execute();
140
```
141

142
### Environment Configuration
143

144
Configure the test environment for parallel execution with restricted options.
145

146
```javascript { .api }
147
/**
148
 * Configure the test environment for parallel execution
149
 * @param envConfig - Environment configuration (specFilter not supported)
150
 */
151
configureEnv(envConfig: ParallelEnvConfig): void;
152

153
interface ParallelEnvConfig {
154
  /** Whether to fail specs that contain no expectations */
155
  failSpecWithNoExpectations?: boolean;
156
  /** Whether to stop each spec on the first expectation failure */
157
  stopSpecOnExpectationFailure?: boolean;
158
  /** Whether to stop suite execution on the first spec failure */
159
  stopOnSpecFailure?: boolean;
160
  /** Whether to run specs in a random order (always true in parallel) */
161
  random?: boolean;
162
  /** Whether to show verbose deprecation warnings */
163
  verboseDeprecations?: boolean;
164
  // Note: specFilter is not supported in parallel mode
165
}
166
```
167

168
**Usage Example:**
169

170
```javascript
171
const runner = new ParallelRunner({ numWorkers: 4 });
172

173
// Configure environment for parallel execution
174
runner.configureEnv({
175
  stopOnSpecFailure: true,     // Stop all workers on first failure
176
  failSpecWithNoExpectations: true,
177
  verboseDeprecations: false
178
});
179

180
await runner.execute();
181
```
182

183
### Parallel Execution Limitations
184

185
Important constraints and limitations when using parallel mode:
186

187
**Unsupported Features:**
188
- Custom `specFilter` functions (only string regex filters supported)
189
- Random seed setting (always uses random seeds)
190
- Disabling randomization (always randomized)
191
- Reporters without `reporterCapabilities.parallel: true`
192

193
**Worker Process Behavior:**
194
- Each worker runs in a separate Node.js process
195
- Global state is not shared between workers
196
- Specs are distributed randomly across workers
197
- Workers can exit unexpectedly and will be reported as fatal errors
198

199
**Error Handling:**
200
- Uncaught exceptions and unhandled rejections in workers are captured
201
- Fatal errors in workers cause the entire suite to fail
202
- Worker disconnection is detected and reported
203

204
**Usage Example with Error Handling:**
205

206
```javascript
207
const ParallelRunner = require('jasmine/parallel');
208

209
const runner = new ParallelRunner({ numWorkers: 4 });
210

211
// Set exit behavior
212
runner.exitOnCompletion = false; // Handle results programmatically
213

214
try {
215
  const result = await runner.execute();
216
  
217
  if (result.overallStatus === 'failed') {
218
    console.error('Tests failed:', result.failedExpectations);
219
    process.exit(1);
220
  } else {
221
    console.log(`Tests passed in ${result.totalTime}ms using ${result.numWorkers} workers`);
222
  }
223
} catch (error) {
224
  console.error('Fatal error during parallel execution:', error);
225
  process.exit(1);
226
}
227
```
228

229
### Configuration and File Management
230

231
Load configuration and manage spec/helper files for parallel execution.
232

233
```javascript { .api }
234
/**
235
 * Loads configuration from the specified file
236
 * @param configFilePath - Path to config file, defaults to spec/support/jasmine.json
237
 */
238
loadConfigFile(configFilePath?: string): Promise<void>;
239

240
/**
241
 * Loads configuration from the specified object
242
 * @param config - Configuration object
243
 */
244
loadConfig(config: Configuration): void;
245
```
246

247
### Display and Output Control
248

249
Control test output formatting and verbosity for parallel execution.
250

251
```javascript { .api }
252
/**
253
 * Sets whether to show colors in the console reporter
254
 * @param value - Whether to show colors
255
 */
256
showColors(value: boolean): void;
257

258
/**
259
 * Sets whether to run in verbose mode for debugging configuration problems
260
 * @param value - Whether to run in verbose mode
261
 */
262
verbose(value: boolean): void;
263

264
/**
265
 * Sets whether the console reporter should list pending specs even when there are failures
266
 * @param value - Whether to always list pending specs
267
 */
268
alwaysListPendingSpecs(value: boolean): void;
269
```
270

271
**Usage Example:**
272

273
```javascript
274
const ParallelRunner = require('jasmine/parallel');
275

276
const runner = new ParallelRunner({ numWorkers: 4 });
277

278
// Load configuration
279
await runner.loadConfigFile('config/parallel-test.json');
280

281
// Set display options
282
runner.showColors(true);
283
runner.verbose(true);
284
runner.alwaysListPendingSpecs(false);
285

286
await runner.execute();
287
```