0
# Configuration Management
1

2
Configuration loading and validation for different Jest project types including custom projects and Create React App setups. Handles Jest config merging and validation.
3

4
## Capabilities
5

6
### Jest Configuration Options
7

8
Core configuration interface for customizing Jest runner behavior within Stryker.
9

10
```typescript { .api }
11
/**
12
 * Jest-specific configuration options for Stryker Jest runner
13
 */
14
export interface JestOptions {
15
  /** Type of Jest project setup */
16
  projectType: JestProjectType;
17
  /** Path to Jest configuration file (optional) */
18
  configFile?: string;
19
  /** Custom Jest configuration object (optional) */
20
  config?: { [k: string]: unknown };
21
  /** Enable Jest's --findRelatedTests flag for optimized test execution */
22
  enableFindRelatedTests: boolean;
23
}
24

25
/**
26
 * Supported Jest project types
27
 */
28
export type JestProjectType = 'create-react-app' | 'custom';
29
```
30

31
**Usage Examples:**
32

33
```javascript
34
// stryker.conf.js - Custom project configuration
35
module.exports = {
36
  testRunner: "jest",
37
  jest: {
38
    projectType: "custom",
39
    configFile: "./jest.config.js",
40
    enableFindRelatedTests: true,
41
    config: {
42
      testEnvironment: "node",
43
      collectCoverageFrom: ["src/**/*.{js,ts}"],
44
      coverageReporters: ["text", "lcov"]
45
    }
46
  }
47
};
48
```
49

50
```javascript
51
// stryker.conf.js - Create React App project  
52
module.exports = {
53
  testRunner: "jest",
54
  jest: {
55
    projectType: "create-react-app",
56
    enableFindRelatedTests: false
57
  }
58
};
59
```
60

61
### Complete Options Interface
62

63
Root configuration interface that combines Jest options with Stryker options.
64

65
```typescript { .api }
66
/**
67
 * Root Jest runner options interface
68
 */
69
export interface JestRunnerOptions {
70
  jest: JestOptions;
71
  [k: string]: unknown;
72
}
73

74
/**
75
 * Combined interface extending Stryker core options with Jest options
76
 */
77
export interface JestRunnerOptionsWithStrykerOptions extends StrykerOptions, JestRunnerOptions {}
78
```
79

80
**Usage Example:**
81

82
```typescript
83
import { JestRunnerOptionsWithStrykerOptions } from "@stryker-mutator/jest-runner";
84

85
// Used internally by Stryker to type check complete configuration
86
const config: JestRunnerOptionsWithStrykerOptions = {
87
  // Stryker core options
88
  mutate: ['src/**/*.js'],
89
  testRunner: 'jest',
90
  coverageAnalysis: 'perTest',
91
  
92
  // Jest-specific options
93
  jest: {
94
    projectType: 'custom',
95
    enableFindRelatedTests: true,
96
    config: {
97
      testMatch: ['**/__tests__/**/*.test.js']
98
    }
99
  }
100
};
101
```
102

103
### Configuration Loaders
104

105
Abstract interface and implementations for loading Jest configuration from different sources.
106

107
```typescript { .api }
108
/**
109
 * Base interface for Jest configuration loaders
110
 */
111
export interface JestConfigLoader {
112
  loadConfig(): Promise<Config.InitialOptions>;
113
}
114

115
/**
116
 * Configuration loader for custom Jest projects
117
 * Loads configuration from Jest config files, package.json, or defaults
118
 */
119
export class CustomJestConfigLoader implements JestConfigLoader {
120
  loadConfig(): Promise<Config.InitialOptions>;
121
}
122

123
/**
124
 * Configuration loader for Create React App projects
125
 * Uses react-scripts Jest configuration with CRA-specific optimizations
126
 */
127
export class ReactScriptsJestConfigLoader implements JestConfigLoader {
128
  loadConfig(): Promise<Config.InitialOptions>;
129
}
130

131
/**
132
 * Factory function to create appropriate config loader based on project type
133
 * @param options - Stryker options containing Jest configuration
134
 * @param injector - Dependency injector for creating loader instances
135
 * @param log - Logger for configuration warnings and debug information
136
 * @returns Configured Jest config loader instance
137
 */
138
export function configLoaderFactory(
139
  options: StrykerOptions,
140
  injector: Injector<JestPluginContext>,
141
  log: Logger
142
): CustomJestConfigLoader | ReactScriptsJestConfigLoader;
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { configLoaderFactory, CustomJestConfigLoader } from "@stryker-mutator/jest-runner";
149

150
// Typically used internally by Stryker through dependency injection
151
const loader = configLoaderFactory(options, injector, logger);
152
const jestConfig = await loader.loadConfig();
153

154
// Direct usage for custom scenarios  
155
const customLoader = new CustomJestConfigLoader(/* dependencies */);
156
const config = await customLoader.loadConfig();
157
```
158

159
### Jest Override Options
160

161
Default configuration overrides applied by Stryker for optimal mutation testing performance.
162

163
```typescript { .api }
164
/**
165
 * Default Jest configuration overrides for Stryker integration
166
 * Applied to all Jest configurations to optimize for mutation testing
167
 */
168
export const JEST_OVERRIDE_OPTIONS: Readonly<Config.InitialOptions>;
169
```
170

171
The override options disable Jest features that interfere with mutation testing:
172

173
```typescript
174
const JEST_OVERRIDE_OPTIONS = {
175
  // Prevent conflicts with Stryker's result processing
176
  testResultsProcessor: undefined,
177
  
178
  // Disable Jest's built-in coverage collection (Stryker handles this)
179
  collectCoverage: false,
180
  
181
  // Reduce verbose output during mutation testing
182
  verbose: false,
183
  
184
  // Disable desktop notifications during testing
185
  notify: false,
186
  
187
  // Ensure all tests run (bail not supported programmatically)
188
  bail: false,
189
  
190
  // Disable default reporters for cleaner output
191
  reporters: [],
192
};
193
```
194

195
**Usage Example:**
196

197
```typescript
198
import { JEST_OVERRIDE_OPTIONS } from "@stryker-mutator/jest-runner";
199

200
// These overrides are automatically applied by the Jest runner
201
// but can be inspected for debugging or custom integrations
202
console.log('Stryker Jest overrides:', JEST_OVERRIDE_OPTIONS);
203

204
// Example of manual config merging (typically done internally)
205
const finalConfig = {
206
  ...userJestConfig,
207
  ...customOptions,
208
  ...JEST_OVERRIDE_OPTIONS  // Applied last to ensure overrides take effect
209
};
210
```
211

212
## Types
213

214
### Configuration Schema Types
215

216
```typescript { .api }
217
// From Jest types
218
namespace Config {
219
  interface InitialOptions {
220
    testEnvironment?: string;
221
    testRunner?: string;
222
    setupFiles?: string[];
223
    setupFilesAfterEnv?: string[];
224
    testMatch?: string[];
225
    testPathIgnorePatterns?: string[];
226
    collectCoverageFrom?: string[];
227
    coverageDirectory?: string;
228
    roots?: string[];
229
    globals?: { [key: string]: any };
230
    // ... many more Jest configuration options
231
  }
232
  
233
  interface GlobalConfig extends InitialOptions {
234
    // Resolved global configuration
235
  }
236
  
237
  interface ProjectConfig extends InitialOptions {
238
    // Resolved project-specific configuration
239
  }
240
}
241
```
242

243
### Stryker Integration Types
244

245
```typescript { .api }
246
interface StrykerOptions {
247
  mutate: string[];
248
  testRunner: string;
249
  coverageAnalysis: CoverageAnalysis;
250
  files: string[];
251
  // ... other Stryker core options
252
}
253

254
type CoverageAnalysis = 'off' | 'all' | 'perTest';
255
```
256

257
### Dependency Injection Types
258

259
```typescript { .api }
260
interface JestPluginContext extends PluginContext {
261
  [pluginTokens.jestWrapper]: JestWrapper;
262
  [pluginTokens.resolve]: RequireResolve;
263
  [pluginTokens.requireFromCwd]: typeof requireResolve;
264
  [pluginTokens.processEnv]: typeof process.env;
265
  [pluginTokens.jestConfigWrapper]: JestConfigWrapper;
266
}
267

268
const pluginTokens = {
269
  requireFromCwd: 'requireFromCwd',
270
  resolve: 'resolve',
271
  resolveFromDirectory: 'resolveFromDirectory',
272
  configLoader: 'configLoader',
273
  processEnv: 'processEnv',
274
  jestTestAdapter: 'jestTestAdapter',
275
  globalNamespace: 'globalNamespace',
276
  jestWrapper: 'jestWrapper',
277
  jestConfigWrapper: 'jestConfigWrapper',
278
} as const;
279
```
280

281
## Configuration Merging Strategy
282

283
The Jest runner applies a layered configuration approach:
284

285
### 1. Base Configuration
286
Loaded from Jest configuration sources in priority order:
287
- Explicit `configFile` path
288
- `jest.config.js` / `jest.config.ts`
289
- `package.json` jest property
290
- Jest defaults
291

292
### 2. User Configuration  
293
Applied from Stryker jest.config option:
294
```javascript
295
jest: {
296
  config: {
297
    // User overrides applied here
298
    testEnvironment: "jsdom",
299
    setupFilesAfterEnv: ["./test-setup.js"]
300
  }
301
}
302
```
303

304
### 3. Stryker Overrides
305
Internal optimizations for mutation testing:
306
```typescript
307
const JEST_OVERRIDE_OPTIONS = {
308
  testResultsProcessor: undefined,    // Prevent conflicts
309
  collectCoverage: false,            // Handled by Stryker
310
  verbose: false,                    // Reduce noise
311
  notify: false,                     // Disable notifications  
312
  bail: false,                       // Run all tests
313
  reporters: [],                     // Disable default reporters
314
};
315
```
316

317
### 4. Runtime Modifications
318
Applied during test execution:
319
- Coverage analysis environment setup
320
- Hit limit environment configuration
321
- Test file path adjustments
322
- Global namespace injection
323

324
## Project Type Behaviors
325

326
### Custom Projects (`projectType: "custom"`)
327

328
- **Config Loading**: Uses standard Jest configuration resolution
329
- **Config File Support**: Respects `configFile` option for custom paths
330
- **Flexibility**: Full access to Jest configuration options
331
- **Use Case**: Most Node.js and custom TypeScript projects
332

333
```javascript
334
jest: {
335
  projectType: "custom",
336
  configFile: "./config/jest.config.js",
337
  config: {
338
    preset: "ts-jest",
339
    testEnvironment: "node"
340
  }
341
}
342
```
343

344
### Create React App Projects (`projectType: "create-react-app"`)
345

346
- **Config Loading**: Uses react-scripts Jest configuration
347
- **Config File Ignored**: `configFile` option ignored with warning
348
- **CRA Optimizations**: Leverages CRA's built-in Jest setup
349
- **Use Case**: Projects created with create-react-app
350

351
```javascript
352
jest: {
353
  projectType: "create-react-app",
354
  enableFindRelatedTests: false  // Often disabled for CRA
355
}
356
```
357

358
## Performance Optimizations
359

360
### Related Tests (`enableFindRelatedTests`)
361

362
When enabled, Jest runs only tests related to mutated files:
363
- **Faster Execution**: Reduces test execution time
364
- **Smart Filtering**: Uses Jest's dependency analysis
365
- **Mutation Testing**: Ideal for large codebases
366
- **Trade-off**: May miss some integration test scenarios
367

368
### Configuration Caching
369

370
- **Loaded Once**: Configuration loaded during initialization
371
- **Merged Strategically**: Applied in optimal order
372
- **Validated Early**: Schema validation prevents runtime errors
373
- **Dependency Resolved**: External dependencies resolved upfront
374

375
### Environment Optimization
376

377
- **Minimal Setup**: Only necessary Jest features enabled
378
- **Disabled Features**: Coverage, reporters, and notifications turned off
379
- **Environment Variables**: Optimized for test execution speed
380
- **Memory Management**: Efficient cleanup after test runs