0
# Configuration
1

2
Testem's flexible configuration system supports multiple file formats and extensive customization options for test execution, browser launching, and reporting.
3

4
## Capabilities
5

6
### Configuration File Formats
7

8
Testem supports multiple configuration file formats with automatic discovery.
9

10
```javascript { .api }
11
// testem.json - JSON format
12
{
13
  "framework": "jasmine",
14
  "src_files": ["src/**/*.js", "spec/**/*.js"],
15
  "launch_in_ci": ["Chrome", "Firefox"]
16
}
17

18
// testem.yml - YAML format  
19
framework: jasmine
20
src_files:
21
  - "src/**/*.js"
22
  - "spec/**/*.js"
23
launch_in_ci:
24
  - Chrome
25
  - Firefox
26

27
// testem.js - JavaScript/CommonJS format
28
module.exports = {
29
  framework: 'jasmine',
30
  src_files: ['src/**/*.js', 'spec/**/*.js'],
31
  launch_in_ci: ['Chrome', 'Firefox']
32
};
33
```
34

35
### Core Configuration Options
36

37
Essential configuration options for test execution and file management.
38

39
```javascript { .api }
40
interface CoreConfig {
41
  // Test Framework
42
  framework?: string;              // jasmine, qunit, mocha, or custom
43

44
  // File Management  
45
  src_files?: string[];           // Source files to include (glob patterns)
46
  src_files_ignore?: string[];    // Files to exclude (glob patterns)
47
  serve_files?: string[];         // Files to serve (defaults to src_files)
48
  watch_files?: string[];         // Files to watch (defaults to src_files)
49
  css_files?: string[];           // CSS files to include
50

51
  // Test Pages
52
  test_page?: string | string[];  // Custom test page(s)
53
  
54
  // Directory Settings
55
  cwd?: string;                   // Working directory
56
  config_dir?: string;            // Config resolution directory
57
}
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
// Basic file configuration
64
{
65
  "src_files": [
66
    "src/**/*.js",
67
    "test/**/*.js"
68
  ],
69
  "src_files_ignore": [
70
    "src/vendor/*.js",
71
    "**/*.min.js"
72
  ]
73
}
74

75
// Custom test page
76
{
77
  "test_page": "custom-test.html",
78
  "serve_files": ["dist/bundle.js"]
79
}
80

81
// Multiple test pages  
82
{
83
  "test_page": [
84
    "unit-tests.html",
85
    "integration-tests.html"
86
  ]
87
}
88
```
89

90
### Server Configuration
91

92
Configure testem's built-in server and networking options.
93

94
```javascript { .api }
95
interface ServerConfig {
96
  // Server Settings
97
  port?: number;                  // Server port (default: 7357)
98
  host?: string;                  // Server host (default: localhost)
99
  
100
  // Routing
101
  routes?: Record<string, string | string[]>; // Custom route mappings
102
  proxies?: Record<string, ProxyConfig>;      // Proxy configuration
103
  middleware?: Function[];        // Express middleware functions
104
  
105
  // Security
106
  unsafe_file_serving?: boolean;  // Allow serving outside CWD
107
}
108

109
interface ProxyConfig {
110
  target: string;                 // Proxy target URL
111
  secure?: boolean;               // Verify SSL certificates  
112
  ws?: boolean;                   // WebSocket proxy
113
  onlyContentTypes?: string[];    // Content type filter
114
}
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
// Basic server config
121
{
122
  "port": 8080,
123
  "host": "0.0.0.0"
124
}
125

126
// Custom routes
127
{
128
  "routes": {
129
    "/api": "mock-api",
130
    "/assets": ["static", "fallback"]
131
  }
132
}
133

134
// Proxy configuration
135
{
136
  "proxies": {
137
    "/api": {
138
      "target": "http://localhost:3000",
139
      "secure": false
140
    },
141
    "/ws": {
142
      "target": "ws://localhost:3001", 
143
      "ws": true
144
    }
145
  }
146
}
147
```
148

149
### Launcher Configuration
150

151
Configure browser and process launchers for different execution environments.
152

153
```javascript { .api }
154
interface LauncherConfig {
155
  // Built-in Launcher Control
156
  launch_in_dev?: string[];       // Launchers for development mode
157
  launch_in_ci?: string[];        // Launchers for CI mode
158
  
159
  // Browser Customization
160
  browser_args?: Record<string, string[] | string | BrowserArgsByMode>;
161
  browser_paths?: Record<string, string>;    // Custom browser paths
162
  browser_exes?: Record<string, string>;     // Custom browser executables
163
  
164
  // Custom Launchers
165
  launchers?: Record<string, LauncherDefinition>;
166
}
167

168
interface BrowserArgsByMode {
169
  dev?: string[];                 // Args for development mode
170
  ci?: string[];                  // Args for CI mode
171
}
172

173
interface LauncherDefinition {
174
  command?: string;               // Command to execute
175
  exe?: string;                   // Executable path
176
  args?: string[];                // Command arguments
177
  protocol?: string;              // browser, tap, or process
178
}
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
// Basic launcher config
185
{
186
  "launch_in_dev": ["Chrome"],
187
  "launch_in_ci": ["Chrome", "Firefox", "Safari"]
188
}
189

190
// Browser customization
191
{
192
  "browser_args": {
193
    "Chrome": ["--no-sandbox", "--disable-gpu"],
194
    "Firefox": ["--headless"]
195
  },
196
  "browser_paths": {
197
    "Chrome": "/path/to/custom/chrome"
198
  }
199
}
200

201
// Custom launcher
202
{
203
  "launchers": {
204
    "Node": {
205
      "command": "node test/runner.js",
206
      "protocol": "tap"
207
    },
208
    "CustomBrowser": {
209
      "exe": "/path/to/browser",
210
      "args": ["--test-mode"],
211
      "protocol": "browser"
212
    }
213
  }
214
}
215
```
216

217
### Test Execution Configuration
218

219
Configure test execution behavior, timeouts, and parallel processing.
220

221
```javascript { .api }
222
interface ExecutionConfig {
223
  // Timeouts
224
  timeout?: number;               // Browser timeout in seconds
225
  
226
  // Parallel Execution
227
  parallel?: number;              // Max parallel runners (CI mode)
228
  
229
  // Test Behavior
230
  fail_on_zero_tests?: boolean;   // Exit with error if no tests
231
  bail_on_uncaught_error?: boolean; // Exit on uncaught errors
232
  single_run?: boolean;           // Run once and exit
233
  disable_watching?: boolean;     // Disable file watching
234
  
235
  // Reporter Settings
236
  reporter?: string;              // Test reporter (tap, xunit, dot, teamcity)
237
  report_file?: string;           // Output file for reports
238
}
239
```
240

241
**Usage Examples:**
242

243
```javascript
244
// CI execution config
245
{
246
  "timeout": 120,
247
  "parallel": 5,
248
  "fail_on_zero_tests": true,
249
  "bail_on_uncaught_error": true
250
}
251

252
// Custom reporter
253
{
254
  "reporter": "xunit",
255
  "report_file": "test-results.xml"
256
}
257
```
258

259
### Lifecycle Hooks
260

261
Configure hooks that run at different points in the test lifecycle.
262

263
```javascript { .api }
264
interface HookConfig {
265
  on_start?: string | Function;    // Run on suite startup
266
  before_tests?: string | Function; // Run before each test run
267
  after_tests?: string | Function;  // Run after each test run  
268
  on_exit?: string | Function;     // Run before suite exits
269
}
270
```
271

272
**Usage Examples:**
273

274
```javascript
275
// Command hooks
276
{
277
  "on_start": "npm run setup",
278
  "before_tests": "npm run build",
279
  "after_tests": "npm run cleanup",
280
  "on_exit": "npm run teardown"
281
}
282

283
// JavaScript function hooks (testem.js only)
284
module.exports = {
285
  before_tests: function(config, data, callback) {
286
    console.log('Running tests...');
287
    callback();
288
  },
289
  after_tests: function(config, data, callback) {
290
    console.log('Tests completed');
291
    callback();
292
  }
293
};
294
```
295

296
### Advanced Configuration
297

298
Advanced options for specialized use cases and integrations.
299

300
```javascript { .api }
301
interface AdvancedConfig {
302
  // URL and Query Parameters
303
  url?: string;                   // Custom URL for tests
304
  query_params?: Record<string, any> | string; // Query parameters
305
  
306
  // TAP Reporter Options
307
  tap_failed_tests_only?: boolean; // Only output failed tests
308
  tap_quiet_logs?: boolean;        // Only log failures
309
  tap_strict_spec_compliance?: boolean; // Strict TAP compliance
310
  tap_log_processor?: Function;    // Custom log processor
311
  
312
  // Development Features
313
  growl?: boolean;                // Native notifications
314
  socket_heartbeat_timeout?: number; // Socket timeout
315
}
316
```
317

318
**Usage Examples:**
319

320
```javascript
321
// Query parameters
322
{
323
  "query_params": {
324
    "env": "test",
325
    "debug": true
326
  }
327
}
328

329
// TAP customization
330
{
331
  "tap_failed_tests_only": true,
332
  "tap_quiet_logs": true
333
}
334
```
335

336
## Configuration Examples
337

338
### Basic Setup
339

340
```javascript
341
// testem.json
342
{
343
  "framework": "jasmine",
344
  "src_files": [
345
    "src/**/*.js",
346
    "spec/**/*.js"
347
  ],
348
  "launch_in_dev": ["Chrome"],
349
  "launch_in_ci": ["Chrome", "Firefox"]
350
}
351
```
352

353
### Advanced Setup
354

355
```javascript
356
// testem.js
357
module.exports = {
358
  framework: 'mocha',
359
  src_files: [
360
    'dist/bundle.js',
361
    'test/**/*.js'
362
  ],
363
  test_page: 'test/index.html',
364
  launch_in_dev: ['Chrome'],
365
  launch_in_ci: ['Chrome', 'Firefox', 'Safari'],
366
  browser_args: {
367
    Chrome: ['--no-sandbox'],
368
    Firefox: ['--headless']
369
  },
370
  proxies: {
371
    '/api': {
372
      target: 'http://localhost:3000'
373
    }
374
  },
375
  before_tests: 'npm run build',
376
  timeout: 60,
377
  parallel: 3,
378
  reporter: 'tap'
379
};
380
```