0
# Configuration Management
1

2
Jasmine provides a comprehensive configuration system supporting JSON and JavaScript config files with CLI overrides, environment variable support, and flexible file loading strategies.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Load configuration from files with automatic discovery and multiple format support.
9

10
```javascript { .api }
11
/**
12
 * Loads configuration from the specified file
13
 * @param configFilePath - Path to config file, defaults to spec/support/jasmine.json
14
 * @returns Promise that resolves when configuration is loaded
15
 */
16
loadConfigFile(configFilePath?: string): Promise<void>;
17

18
/**
19
 * Loads configuration from the specified object
20
 * @param config - Configuration object
21
 */
22
loadConfig(config: Configuration): void;
23
```
24

25
**File Discovery Order:**
26
1. `spec/support/jasmine.mjs` (ES module, preferred)
27
2. `spec/support/jasmine.json` (JSON format)
28
3. `spec/support/jasmine.js` (CommonJS module)
29

30
**Usage Examples:**
31

32
```javascript
33
const Jasmine = require('jasmine');
34
const jasmine = new Jasmine();
35

36
// Load default config file
37
await jasmine.loadConfigFile();
38

39
// Load specific config file
40
await jasmine.loadConfigFile('config/test.json');
41

42
// Load configuration object directly
43
jasmine.loadConfig({
44
  spec_dir: 'test',
45
  spec_files: ['**/*-test.js'],
46
  helpers: ['test/helpers/**/*.js'],
47
  random: true
48
});
49
```
50

51
### Configuration Interface
52

53
Complete configuration object structure with all supported options.
54

55
```javascript { .api }
56
interface Configuration {
57
  /** The directory that spec files are contained in, relative to the project base directory */
58
  spec_dir?: string;
59
  
60
  /** An array of spec file paths or globs that match spec files */
61
  spec_files?: string[];
62
  
63
  /** An array of helper file paths or globs that match helper files */
64
  helpers?: string[];
65
  
66
  /** An array of module names to load at the start of execution */
67
  requires?: string[];
68
  
69
  /** Specifies how to load files with names ending in .js */
70
  jsLoader?: 'import' | 'require';
71
  
72
  /** Whether to fail specs that contain no expectations */
73
  failSpecWithNoExpectations?: boolean;
74
  
75
  /** Whether to stop each spec on the first expectation failure */
76
  stopSpecOnExpectationFailure?: boolean;
77
  
78
  /** Whether to stop suite execution on the first spec failure */
79
  stopOnSpecFailure?: boolean;
80
  
81
  /** Whether the default reporter should list pending specs even if there are failures */
82
  alwaysListPendingSpecs?: boolean;
83
  
84
  /** Whether to run specs in a random order */
85
  random?: boolean;
86
  
87
  /** Whether to show verbose deprecation warnings */
88
  verboseDeprecations?: boolean;
89
  
90
  /** An array of reporters (JavaScript config files only) */
91
  reporters?: Reporter[];
92
  
93
  /** A function that will be called exactly once before the test suite runs */
94
  globalSetup?: () => void | Promise<void>;
95
  
96
  /** The number of milliseconds to wait for an asynchronous globalSetup to complete */
97
  globalSetupTimeout?: number;
98
  
99
  /** A function that will be called exactly once after the test suite runs */
100
  globalTeardown?: () => void | Promise<void>;
101
  
102
  /** The number of milliseconds to wait for an asynchronous globalTeardown to complete */
103
  globalTeardownTimeout?: number;
104
  
105
  /** Environment configuration passed to jasmine-core */
106
  env?: object;
107
}
108
```
109

110
### File and Module Configuration
111

112
Configure spec files, helpers, and required modules with glob pattern support.
113

114
```javascript { .api }
115
/**
116
 * Adds files that match the specified patterns to the list of spec files
117
 * @param patterns - Array of spec file paths or globs relative to spec directory
118
 */
119
addMatchingSpecFiles(patterns: string[]): void;
120

121
/**
122
 * Adds files that match the specified patterns to the list of helper files
123
 * @param patterns - Array of helper file paths or globs relative to spec directory
124
 */
125
addMatchingHelperFiles(patterns: string[]): void;
126

127
/**
128
 * Adds a single spec file to the list
129
 * @param filePath - The path to the file to be loaded
130
 */
131
addSpecFile(filePath: string): void;
132

133
/**
134
 * Adds a single helper file to the list
135
 * @param filePath - The path to the file to be loaded
136
 */
137
addHelperFile(filePath: string): void;
138

139
/**
140
 * Adds required modules to be loaded at startup
141
 * @param requires - Array of module names to require
142
 */
143
addRequires(requires: string[]): void;
144

145
/**
146
 * Configures the default reporter that is installed if no other reporter is specified
147
 * @param options - Configuration options for the default console reporter
148
 */
149
configureDefaultReporter(options: ConsoleReporterOptions): void;
150

151
interface ConsoleReporterOptions {
152
  /** Whether to colorize the output */
153
  showColors?: boolean;
154
  /** Custom print function for output */
155
  print?: (text: string) => void;
156
  /** Function to filter/modify stack traces */
157
  stackFilter?: (stack: string) => string;
158
  /** Function that takes a random seed and returns the command to reproduce that seed */
159
  randomSeedReproductionCmd?: (seed: string) => string;
160
  /** Whether to list pending specs even if there are failures */
161
  alwaysListPendingSpecs?: boolean;
162
}
163
```
164

165
**Usage Examples:**
166

167
```javascript
168
const jasmine = new Jasmine();
169

170
// Add spec files with glob patterns
171
jasmine.addMatchingSpecFiles([
172
  '**/*-spec.js',
173
  '**/*-test.js',
174
  '!**/*-integration-test.js' // Exclude integration tests
175
]);
176

177
// Add helper files
178
jasmine.addMatchingHelperFiles([
179
  'helpers/**/*.js',
180
  'support/**/*.js'
181
]);
182

183
// Add individual files
184
jasmine.addSpecFile('spec/unit/user-service.spec.js');
185
jasmine.addHelperFile('spec/helpers/database-helper.js');
186

187
// Add required modules
188
jasmine.addRequires(['@babel/register', 'tsconfig-paths/register']);
189
```
190

191
### JavaScript Module Loading
192

193
Configure module loading strategy for ES modules and CommonJS compatibility.
194

195
```javascript { .api }
196
// Configuration options for module loading
197
interface ModuleLoadingConfig {
198
  /** Specifies how to load files with names ending in .js */
199
  jsLoader: 'import' | 'require';
200
}
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
// ES module configuration (jasmine.mjs)
207
export default {
208
  spec_dir: 'spec',
209
  spec_files: ['**/*-spec.mjs'],
210
  jsLoader: 'import', // Use dynamic import()
211
  env: {
212
    forbidDuplicateNames: true
213
  }
214
};
215

216
// CommonJS configuration (jasmine.json)
217
{
218
  "spec_dir": "test",
219
  "spec_files": ["**/*-test.js"],
220
  "jsLoader": "require",
221
  "random": true
222
}
223

224
// Mixed environment handling
225
const config = {
226
  spec_dir: 'spec',
227
  spec_files: [
228
    '**/*-spec.js',   // CommonJS specs
229
    '**/*-spec.mjs'   // ES module specs
230
  ],
231
  jsLoader: 'import', // Use import for better compatibility
232
  helpers: ['helpers/**/*.js']
233
};
234
```
235

236
### Global Setup and Teardown
237

238
Configure global setup and teardown functions for test suite initialization and cleanup.
239

240
```javascript { .api }
241
interface GlobalHooksConfig {
242
  /** A function that will be called exactly once before the test suite runs */
243
  globalSetup?: () => void | Promise<void>;
244
  
245
  /** The number of milliseconds to wait for globalSetup to complete (default: 5000) */
246
  globalSetupTimeout?: number;
247
  
248
  /** A function that will be called exactly once after the test suite runs */
249
  globalTeardown?: () => void | Promise<void>;
250
  
251
  /** The number of milliseconds to wait for globalTeardown to complete (default: 5000) */
252
  globalTeardownTimeout?: number;
253
}
254
```
255

256
**Usage Examples:**
257

258
```javascript
259
// JavaScript config file (jasmine.js)
260
const { spawn } = require('child_process');
261

262
module.exports = {
263
  spec_dir: 'spec',
264
  spec_files: ['**/*-spec.js'],
265
  
266
  globalSetup: async () => {
267
    console.log('Starting test database...');
268
    // Start database, create test data, etc.
269
    await startTestDatabase();
270
  },
271
  
272
  globalSetupTimeout: 10000, // 10 seconds
273
  
274
  globalTeardown: async () => {
275
    console.log('Cleaning up test environment...');
276
    // Stop database, clean up files, etc.
277
    await stopTestDatabase();
278
  },
279
  
280
  globalTeardownTimeout: 5000 // 5 seconds
281
};
282

283
async function startTestDatabase() {
284
  // Implementation for starting test database
285
}
286

287
async function stopTestDatabase() {
288
  // Implementation for stopping test database
289
}
290
```
291

292
### Reporter Configuration
293

294
Configure multiple reporters in JavaScript configuration files.
295

296
```javascript { .api }
297
interface ReporterConfig {
298
  /** An array of reporters (only supported in JavaScript config files) */
299
  reporters?: Reporter[];
300
}
301

302
interface Reporter {
303
  jasmineStarted?(suiteInfo: any): void;
304
  jasmineDone?(suiteInfo: any): void;
305
  specDone?(result: any): void;
306
  suiteDone?(result: any): void;
307
  reporterCapabilities?: { parallel?: boolean };
308
}
309
```
310

311
**Usage Example:**
312

313
```javascript
314
// jasmine.js config file
315
const fs = require('fs');
316

317
const customReporter = {
318
  specDone: (result) => {
319
    if (result.status === 'failed') {
320
      fs.appendFileSync('failed-specs.log', `${result.fullName}\n`);
321
    }
322
  }
323
};
324

325
const parallelReporter = {
326
  reporterCapabilities: { parallel: true },
327
  jasmineDone: (result) => {
328
    console.log(`Tests completed: ${result.overallStatus}`);
329
  }
330
};
331

332
module.exports = {
333
  spec_dir: 'spec',
334
  spec_files: ['**/*-spec.js'],
335
  reporters: [customReporter, parallelReporter]
336
};
337
```
338

339
### Environment Variable Support
340

341
Override configuration using environment variables and CLI arguments.
342

343
**Environment Variables:**
344
- `JASMINE_CONFIG_PATH`: Path to configuration file
345

346
**Usage Examples:**
347

348
```bash
349
# Use custom config file
350
JASMINE_CONFIG_PATH=config/ci.json npx jasmine
351

352
# CLI overrides take precedence over config file
353
npx jasmine --config=config/local.json --parallel=4 --verbose
354
```
355

356
### Default Configuration Example
357

358
Complete example configuration showing all available options:
359

360
```javascript
361
// spec/support/jasmine.mjs
362
export default {
363
  // File locations
364
  spec_dir: 'spec',
365
  spec_files: [
366
    '**/*[sS]pec.?(m)js'
367
  ],
368
  helpers: [
369
    'helpers/**/*.?(m)js'
370
  ],
371
  requires: [
372
    '@babel/register'
373
  ],
374
  
375
  // Module loading
376
  jsLoader: 'import',
377
  
378
  // Test execution behavior
379
  failSpecWithNoExpectations: false,
380
  stopSpecOnExpectationFailure: false,
381
  stopOnSpecFailure: false,
382
  alwaysListPendingSpecs: true,
383
  random: true,
384
  verboseDeprecations: false,
385
  
386
  // Global hooks
387
  globalSetupTimeout: 5000,
388
  globalTeardownTimeout: 5000,
389
  
390
  // Environment configuration passed to jasmine-core
391
  env: {
392
    forbidDuplicateNames: true,
393
    throwOnExpectationFailure: false,
394
    random: true,
395
    hideDisabled: false
396
  }
397
};
398
```