0
# Configuration
1

2
Flexible configuration system for controlling test execution, filtering tests, setting timeouts, customizing behavior, and configuring reporters.
3

4
## Capabilities
5

6
### Test Execution Configuration
7

8
Control how tests are executed and managed.
9

10
```javascript { .api }
11
/**
12
 * @typedef {Object} QUnitConfig
13
 * @property {boolean} autostart - Automatically start tests when page loads (default: true)
14
 * @property {boolean} reorder - Run failed tests first in subsequent runs (default: true)
15
 * @property {boolean} requireExpects - Require assert.expect() calls in all tests (default: false)
16
 * @property {number} testTimeout - Global test timeout in milliseconds
17
 * @property {string|boolean} seed - Seed for randomizing test order
18
 * @property {boolean} failOnZeroTests - Fail when no tests are run (default: true)
19
 */
20
QUnit.config.autostart
21
QUnit.config.reorder
22
QUnit.config.requireExpects
23
QUnit.config.testTimeout
24
QUnit.config.seed
25
QUnit.config.failOnZeroTests
26
```
27

28
**Usage Examples:**
29

30
```javascript
31
import QUnit from "qunit";
32

33
// Disable autostart for manual control
34
QUnit.config.autostart = false;
35

36
// Load resources then start
37
loadTestDependencies().then(() => {
38
  QUnit.start();
39
});
40

41
// Require expect calls in all tests
42
QUnit.config.requireExpects = true;
43

44
// Set global timeout
45
QUnit.config.testTimeout = 2000; // 2 seconds
46

47
// Use specific seed for reproducible test order
48
QUnit.config.seed = "12345";
49
```
50

51
### Test Filtering Configuration
52

53
Filter which tests run based on various criteria.
54

55
```javascript { .api }
56
/**
57
 * Test filtering configuration properties
58
 */
59
QUnit.config.filter    // Filter tests by name pattern (string or regex)
60
QUnit.config.module    // Run only tests in specified module
61
QUnit.config.moduleId  // Run only modules with specified IDs (array)
62
QUnit.config.testId    // Run only tests with specified IDs (array)
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
// Run only tests matching pattern
69
QUnit.config.filter = "user";
70

71
// Run only specific module
72
QUnit.config.module = "Authentication";
73

74
// Run specific tests by ID
75
QUnit.config.testId = ["test-123", "test-456"];
76

77
// Run specific modules by ID
78
QUnit.config.moduleId = ["module-auth", "module-users"];
79
```
80

81
### Display Configuration
82

83
Customize how test results are displayed in browser environments.
84

85
```javascript { .api }
86
/**
87
 * Display configuration properties for HTML reporter
88
 */
89
QUnit.config.altertitle  // Modify document title on completion (default: true)
90
QUnit.config.collapse    // Collapse passing tests in HTML reporter (default: true)
91
QUnit.config.scrolltop   // Scroll to top when tests complete (default: true)
92
QUnit.config.hidepassed  // Hide passed tests in HTML reporter
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
// Keep document title unchanged
99
QUnit.config.altertitle = false;
100

101
// Show all tests expanded
102
QUnit.config.collapse = false;
103

104
// Hide passing tests to focus on failures
105
QUnit.config.hidepassed = true;
106

107
// Don't scroll to top when done
108
QUnit.config.scrolltop = false;
109
```
110

111
### Development Configuration
112

113
Settings for development and debugging scenarios.
114

115
```javascript { .api }
116
/**
117
 * Development and debugging configuration properties
118
 */
119
QUnit.config.noglobals       // Check for global variable leaks (default: false)
120
QUnit.config.notrycatch      // Disable try-catch for easier debugging (default: false)
121
QUnit.config.maxDepth        // Maximum depth for object comparison (default: 5)
122
QUnit.config.countStepsAsOne // Count assert.step() as single assertion (default: false)
123
QUnit.config.updateRate      // Rate for UI updates in milliseconds (default: 1000)
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
// Enable global leak detection
130
QUnit.config.noglobals = true;
131

132
// Disable try-catch for debugging
133
QUnit.config.notrycatch = true;
134

135
// Increase comparison depth for complex objects
136
QUnit.config.maxDepth = 10;
137

138
// Count multiple steps as one assertion
139
QUnit.config.countStepsAsOne = true;
140
```
141

142
### Reporter Configuration
143

144
Configure built-in reporters and their behavior.
145

146
```javascript { .api }
147
/**
148
 * Reporter configuration object
149
 */
150
QUnit.config.reporters = {
151
  console: false,  // Enable console reporter for Node.js
152
  tap: false      // Enable TAP reporter
153
}
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
// Enable console reporter in Node.js
160
QUnit.config.reporters.console = true;
161

162
// Enable TAP output
163
QUnit.config.reporters.tap = true;
164

165
// Disable all built-in reporters
166
QUnit.config.reporters.console = false;
167
QUnit.config.reporters.tap = false;
168
```
169

170
### Runtime Configuration Access
171

172
Access current test execution state and statistics.
173

174
```javascript { .api }
175
/**
176
 * Runtime configuration and state (read-only during execution)
177
 */
178
QUnit.config.current   // Currently running test context
179
QUnit.config.modules   // Array of all registered modules
180
QUnit.config.stats     // Test execution statistics
181
QUnit.config.storage   // Storage backend for test state
182
QUnit.config.started   // Timestamp when tests started
183
QUnit.config.blocking  // Whether test execution is paused
184
QUnit.config.queue     // Internal test queue
185

186
// Statistics object structure:
187
QUnit.config.stats = {
188
  all: 0,       // Total assertions
189
  bad: 0,       // Failed assertions  
190
  testCount: 0  // Total tests
191
}
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
QUnit.test("access runtime config", function(assert) {
198
  // Get current test info
199
  const currentTest = QUnit.config.current;
200
  assert.ok(currentTest, "current test is available");
201
  
202
  // Check total test count
203
  assert.ok(QUnit.config.stats.all >= 1, "at least one test registered");
204
  
205
  // Access module information
206
  const modules = QUnit.config.modules;
207
  assert.ok(Array.isArray(modules), "modules array is available");
208
});
209
```
210

211
### URL Parameter Configuration
212

213
Configure tests via URL parameters in browser environments.
214

215
```javascript { .api }
216
// URL parameters automatically update QUnit.config
217
// Examples:
218
// ?filter=user          - Filter tests by "user"
219
// ?module=Auth          - Run only "Auth" module  
220
// ?noglobals=true       - Enable global leak detection
221
// ?notrycatch=true      - Disable try-catch
222
// ?seed=12345          - Set specific seed
223
// ?hidepassed=true     - Hide passed tests
224
```
225

226
**Usage Examples:**
227

228
```html
229
<!-- URL parameter examples -->
230
<a href="test.html?filter=login">Run login tests</a>
231
<a href="test.html?module=UserManager">Run UserManager module</a>
232
<a href="test.html?noglobals=true&notrycatch=true">Debug mode</a>
233
```
234

235
### Configuration Initialization
236

237
Set configuration before tests run.
238

239
```javascript { .api }
240
/**
241
 * Extend configuration with custom options (deprecated in QUnit 3.0)
242
 * @param {Object} options - Configuration options to merge
243
 * @param {boolean} [priority] - Whether to override existing values
244
 * @deprecated Use Object.assign instead
245
 */
246
QUnit.extend(options, priority)
247
```
248

249
**Usage Examples:**
250

251
```javascript
252
// Set multiple configuration options
253
QUnit.extend({
254
  autostart: false,
255
  requireExpects: true,
256
  testTimeout: 5000,
257
  noglobals: true
258
});
259

260
// Override existing configuration
261
QUnit.extend({
262
  filter: "critical"
263
}, true);
264
```
265

266
### Storage Configuration
267

268
Configure persistent storage for test state.
269

270
```javascript { .api }
271
/**
272
 * Storage backend interface (defaults to sessionStorage in browsers)
273
 * @typedef {Object} Storage
274
 * @property {Function} getItem - Get stored value
275
 * @property {Function} setItem - Set stored value  
276
 * @property {Function} removeItem - Remove stored value
277
 * @property {Function} clear - Clear all stored values
278
 */
279
QUnit.config.storage = {
280
  getItem(key) { /* ... */ },
281
  setItem(key, value) { /* ... */ },
282
  removeItem(key) { /* ... */ },
283
  clear() { /* ... */ }
284
}
285
```
286

287
**Usage Examples:**
288

289
```javascript
290
// Custom storage implementation
291
QUnit.config.storage = {
292
  data: new Map(),
293
  
294
  getItem(key) {
295
    return this.data.get(key) || null;
296
  },
297
  
298
  setItem(key, value) {
299
    this.data.set(key, value);
300
  },
301
  
302
  removeItem(key) {
303
    this.data.delete(key);
304
  },
305
  
306
  clear() {
307
    this.data.clear();
308
  }
309
};
310
```
311

312
## Environment Variables and URL Parameters
313

314
QUnit can be configured via environment variables (Node.js) or URL parameters (browser):
315

316
```javascript { .api }
317
// Environment variables (Node.js)
318
process.env.qunit_config_autostart = 'false'
319
process.env.qunit_config_filter = 'login'
320
process.env.qunit_config_module = 'Authentication'
321
process.env.qunit_config_noglobals = 'true'
322
process.env.qunit_config_notrycatch = 'true'
323
process.env.qunit_config_reporters_console = 'true'
324
process.env.qunit_config_reporters_tap = 'true'
325

326
// URL parameters (browser)
327
// ?autostart=false&filter=login&module=Auth&noglobals=true
328
```
329

330
## Configuration Object Structure
331

332
The complete QUnit.config object contains:
333

334
```javascript { .api }
335
/**
336
 * Complete configuration object structure based on QUnit v2.24.1
337
 */
338
QUnit.config = {
339
  // Test execution control
340
  autostart: true,
341
  reorder: true,
342
  requireExpects: false,
343
  testTimeout: undefined,
344
  seed: undefined,
345
  failOnZeroTests: true,
346
  
347
  // Test filtering
348
  filter: '',
349
  module: undefined,
350
  moduleId: undefined,
351
  testId: undefined,
352
  
353
  // Display options  
354
  altertitle: true,
355
  collapse: true,
356
  scrolltop: true,
357
  hidepassed: undefined,
358
  
359
  // Development options
360
  noglobals: undefined,
361
  notrycatch: undefined,
362
  maxDepth: 5,
363
  countStepsAsOne: false,
364
  updateRate: 1000,
365
  
366
  // Reporter configuration
367
  reporters: {},
368
  
369
  // Runtime state (read-only)
370
  current: null,
371
  modules: [],
372
  stats: { all: 0, bad: 0, testCount: 0 },
373
  storage: window.sessionStorage || null,
374
  started: 0,
375
  blocking: true,
376
  
377
  // Internal properties
378
  currentModule: {},
379
  globalHooks: {},
380
  pq: null,
381
  queue: [],
382
  callbacks: {},
383
  urlConfig: []
384
}
385
```