0
# StrykerJS Jest Runner
1
2
StrykerJS Jest Runner is a plugin that enables the use of Jest as a test runner and framework within Stryker, the JavaScript mutation testing framework. It provides seamless integration between Jest and Stryker, supporting advanced features like per-test coverage analysis, multiple Jest environments, and optimized test execution for mutation testing workflows.
3
4
## Package Information
5
6
- **Package Name**: @stryker-mutator/jest-runner
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @stryker-mutator/jest-runner`
10
- **Peer Dependency**: `@stryker-mutator/core ~9.1.0`
11
12
## Core Imports
13
14
```typescript
15
import { strykerPlugins, strykerValidationSchema, mixinJestEnvironment } from "@stryker-mutator/jest-runner";
16
```
17
18
For Jest environment integration:
19
20
```javascript
21
// These are pre-enhanced Jest environments (CommonJS exports)
22
// Node.js environment with Stryker integration
23
const JestEnvironmentNode = require("@stryker-mutator/jest-runner/jest-env/node");
24
25
// JSDOM environment with Stryker integration
26
const JestEnvironmentJsdom = require("@stryker-mutator/jest-runner/jest-env/jsdom");
27
28
// JSDOM v16 environment with Stryker integration
29
const JestEnvironmentJsdomSixteen = require("@stryker-mutator/jest-runner/jest-env/jsdom-sixteen");
30
```
31
32
## Basic Usage
33
34
### Stryker Configuration
35
36
```javascript
37
// stryker.conf.js
38
module.exports = {
39
testRunner: "jest",
40
coverageAnalysis: "perTest", // or "all" or "off"
41
jest: {
42
projectType: "custom", // or "create-react-app"
43
enableFindRelatedTests: true,
44
config: {
45
// Custom Jest configuration
46
testEnvironment: "node"
47
}
48
}
49
};
50
```
51
52
### Jest Environment Integration
53
54
```typescript
55
import { mixinJestEnvironment } from "@stryker-mutator/jest-runner";
56
import { TestEnvironment } from "@jest/environment";
57
58
// Enhance Jest environment with Stryker integration
59
const StrykerJestEnvironment = mixinJestEnvironment(TestEnvironment);
60
```
61
62
## Architecture
63
64
The Jest Runner is built around several key components:
65
66
- **Plugin System**: Integrates with Stryker's plugin architecture using factory pattern
67
- **Test Adapter Pattern**: Abstracts Jest version differences through adapters
68
- **Configuration Management**: Handles Jest config loading for different project types
69
- **Environment Enhancement**: Provides Jest environment mixins for mutation testing
70
- **Coverage Analysis**: Implements per-test and global coverage tracking
71
- **Hit Limiting**: Prevents infinite loops during mutation testing
72
73
## Capabilities
74
75
### Stryker Plugin Integration
76
77
Core plugin registration and validation schema for Stryker integration. Provides the main entry point for using Jest as a test runner in Stryker mutation testing.
78
79
```typescript { .api }
80
export const strykerPlugins: Array<PluginDeclaration>;
81
82
export const strykerValidationSchema: JestRunnerOptionsSchema;
83
```
84
85
[Plugin Integration](./plugin-integration.md)
86
87
### Jest Test Runner
88
89
Main test runner implementation that executes Jest tests within Stryker's mutation testing workflow. Handles dry runs for coverage analysis and mutant runs for testing specific mutations.
90
91
```typescript { .api }
92
export class JestTestRunner implements TestRunner {
93
init(): Promise<void>;
94
capabilities(): TestRunnerCapabilities;
95
dryRun(options: Pick<DryRunOptions, 'coverageAnalysis' | 'files'>): Promise<DryRunResult>;
96
mutantRun(options: MutantRunOptions): Promise<MutantRunResult>;
97
}
98
99
export function createJestTestRunnerFactory(
100
namespace?: typeof INSTRUMENTER_CONSTANTS.NAMESPACE | '__stryker2__'
101
): {
102
(injector: Injector<PluginContext>): JestTestRunner;
103
inject: ['$injector'];
104
};
105
106
export const jestTestRunnerFactory: ReturnType<typeof createJestTestRunnerFactory>;
107
```
108
109
[Test Runner](./test-runner.md)
110
111
### Jest Environment Integration
112
113
Jest environment enhancement utilities that provide Stryker-specific functionality including instrumenter context sharing and test event handling for coverage analysis.
114
115
```typescript { .api }
116
export function mixinJestEnvironment<T extends typeof JestEnvironment>(
117
JestEnvironmentClass: T & { [STRYKER_JEST_ENV]?: true }
118
): T;
119
```
120
121
[Environment Integration](./environment-integration.md)
122
123
### Configuration Management
124
125
Configuration loading and validation for different Jest project types including custom projects and Create React App setups. Handles Jest config merging and validation.
126
127
```typescript { .api }
128
export interface JestOptions {
129
projectType: JestProjectType;
130
configFile?: string;
131
config?: { [k: string]: unknown };
132
enableFindRelatedTests: boolean;
133
}
134
135
export type JestProjectType = 'create-react-app' | 'custom';
136
137
export interface JestRunnerOptions {
138
jest: JestOptions;
139
[k: string]: unknown;
140
}
141
142
export interface JestRunnerOptionsWithStrykerOptions extends StrykerOptions, JestRunnerOptions {}
143
```
144
145
[Configuration Management](./configuration.md)
146
147
### Utility Functions and Classes
148
149
Core utility functions and wrapper classes for Jest integration, version handling, and coverage validation.
150
151
```typescript { .api }
152
export class JestWrapper {
153
getVersion(): string;
154
}
155
156
export class JestConfigWrapper {
157
// Configuration loading and manipulation utilities
158
}
159
160
export function verifyAllTestFilesHaveCoverage(
161
jestResult: AggregatedResult,
162
testFilesWithStrykerEnvironment: Set<string>
163
): string | undefined;
164
165
export function withCoverageAnalysis(
166
jestConfig: Config.InitialOptions,
167
coverageAnalysis: CoverageAnalysis,
168
jestWrapper: JestWrapper
169
): Config.InitialOptions;
170
171
export function withHitLimit(
172
jestConfig: Config.InitialOptions,
173
hitLimit: number | undefined,
174
jestWrapper: JestWrapper
175
): Config.InitialOptions;
176
177
export const JEST_OVERRIDE_OPTIONS: Readonly<Config.InitialOptions>;
178
179
export const pluginTokens: {
180
readonly requireFromCwd: 'requireFromCwd';
181
readonly resolve: 'resolve';
182
readonly resolveFromDirectory: 'resolveFromDirectory';
183
readonly configLoader: 'configLoader';
184
readonly processEnv: 'processEnv';
185
readonly jestTestAdapter: 'jestTestAdapter';
186
readonly globalNamespace: 'globalNamespace';
187
readonly jestWrapper: 'jestWrapper';
188
readonly jestConfigWrapper: 'jestConfigWrapper';
189
};
190
```
191
192
[Utilities](./utilities.md)
193
194
## Types
195
196
### Core Plugin Types
197
198
```typescript { .api }
199
interface PluginDeclaration {
200
kind: PluginKind;
201
name: string;
202
factory: Function;
203
}
204
205
interface TestRunnerCapabilities {
206
reloadEnvironment: boolean;
207
}
208
```
209
210
### Test Execution Types
211
212
```typescript { .api }
213
interface DryRunOptions {
214
coverageAnalysis: CoverageAnalysis;
215
files: string[];
216
}
217
218
interface MutantRunOptions {
219
activeMutant: Mutant;
220
sandboxFileName: string;
221
testFilter?: string[];
222
disableBail: boolean;
223
hitLimit?: number;
224
}
225
226
interface DryRunResult {
227
status: DryRunStatus;
228
tests?: TestResult[];
229
errorMessage?: string;
230
mutantCoverage?: MutantCoverage;
231
}
232
233
interface MutantRunResult {
234
status: MutantRunStatus;
235
tests?: TestResult[];
236
errorMessage?: string;
237
killedBy?: string[];
238
survivalReason?: string;
239
}
240
```
241
242
### Jest Integration Types
243
244
```typescript { .api }
245
interface RunSettings {
246
jestConfig: Config.InitialOptions;
247
testNamePattern?: string;
248
fileNamesUnderTest?: string[];
249
testLocationInResults?: boolean;
250
}
251
252
interface JestRunResult {
253
results: AggregatedResult;
254
globalConfig: Config.GlobalConfig;
255
}
256
257
interface JestTestAdapter {
258
run(settings: RunSettings): Promise<JestRunResult>;
259
}
260
```
261
262
### Jest and Stryker Core Types
263
264
```typescript { .api }
265
// Jest configuration types (from @jest/types)
266
namespace Config {
267
interface InitialOptions {
268
[key: string]: unknown;
269
testEnvironment?: string;
270
collectCoverageFrom?: string[];
271
coverageReporters?: string[];
272
setupFilesAfterEnv?: string[];
273
transform?: { [key: string]: string };
274
testMatch?: string[];
275
testPathIgnorePatterns?: string[];
276
moduleNameMapping?: { [key: string]: string };
277
}
278
279
interface GlobalConfig extends InitialOptions {
280
projects: ProjectConfig[];
281
watch: boolean;
282
watchman: boolean;
283
}
284
285
interface ProjectConfig extends InitialOptions {
286
displayName?: string;
287
rootDir: string;
288
testMatch: string[];
289
}
290
}
291
292
// Jest test result types (from @jest/test-result)
293
interface AggregatedResult {
294
numFailedTests: number;
295
numPassedTests: number;
296
numPendingTests: number;
297
numTotalTests: number;
298
success: boolean;
299
testResults: TestResult[];
300
}
301
302
// Stryker core types
303
type CoverageAnalysis = 'off' | 'all' | 'perTest';
304
305
interface Mutant {
306
id: string;
307
fileName: string;
308
mutatorName: string;
309
replacement: string;
310
range: [number, number];
311
}
312
313
enum DryRunStatus {
314
Complete = 'Complete',
315
Error = 'Error',
316
Timeout = 'Timeout'
317
}
318
319
enum MutantRunStatus {
320
Killed = 'Killed',
321
Survived = 'Survived',
322
Timeout = 'Timeout',
323
Error = 'Error'
324
}
325
326
interface TestResult {
327
id: string;
328
name: string;
329
status: TestStatus;
330
timeSpentMs?: number;
331
failureMessage?: string;
332
}
333
334
enum TestStatus {
335
Success = 'Success',
336
Failed = 'Failed',
337
Skipped = 'Skipped'
338
}
339
340
// Stryker constants
341
const INSTRUMENTER_CONSTANTS = {
342
NAMESPACE: '__stryker__'
343
} as const;
344
```