0
# Launchers
1
2
Testem's launcher system provides pluggable browser and process execution with built-in support for major browsers and custom launcher definitions.
3
4
## Capabilities
5
6
### Built-in Launchers
7
8
Testem includes built-in support for major browsers and runtime environments.
9
10
```javascript { .api }
11
// Built-in browser launchers
12
const builtInBrowsers = [
13
'Chrome', // Google Chrome
14
'Firefox', // Mozilla Firefox
15
'Safari', // Safari (macOS)
16
'Edge', // Microsoft Edge
17
'IE', // Internet Explorer
18
'Opera', // Opera browser
19
'PhantomJS' // Headless PhantomJS
20
];
21
22
// Built-in process launchers
23
const builtInProcesses = [
24
'Node', // Node.js execution
25
'Mocha' // Mocha TAP runner
26
];
27
```
28
29
**Usage Examples:**
30
31
```javascript
32
// Launch specific browsers
33
{
34
"launch_in_dev": ["Chrome", "Firefox"],
35
"launch_in_ci": ["Chrome", "Firefox", "Safari"]
36
}
37
38
// Cross-platform browser launching
39
{
40
"launch_in_ci": ["Chrome", "Firefox", "IE"] // IE only works on Windows
41
}
42
```
43
44
### Launcher Discovery
45
46
Find available launchers on the current system.
47
48
```bash { .api }
49
testem launchers
50
```
51
52
**Example Output:**
53
54
```
55
Have 7 launchers available; auto-launch info displayed on the right.
56
57
Launcher Type CI Dev
58
------------ ------------ -- ---
59
Chrome browser ✔
60
Firefox browser ✔
61
Safari browser ✔
62
IE browser ✔
63
Node process ✔
64
PhantomJS browser ✔
65
Mocha process(TAP) ✔
66
```
67
68
### Browser Customization
69
70
Customize browser behavior with arguments, paths, and executables.
71
72
```javascript { .api }
73
interface BrowserCustomization {
74
// Browser Arguments
75
browser_args?: {
76
[browser: string]: string[] | string | BrowserArgsByMode;
77
};
78
79
// Custom Browser Paths
80
browser_paths?: {
81
[browser: string]: string;
82
};
83
84
// Custom Browser Executables
85
browser_exes?: {
86
[browser: string]: string;
87
};
88
}
89
90
interface BrowserArgsByMode {
91
dev?: string[]; // Arguments for development mode
92
ci?: string[]; // Arguments for CI mode
93
}
94
```
95
96
**Usage Examples:**
97
98
```javascript
99
// Browser arguments
100
{
101
"browser_args": {
102
"Chrome": [
103
"--no-sandbox",
104
"--disable-gpu",
105
"--disable-web-security"
106
],
107
"Firefox": ["--headless"],
108
"Chrome": {
109
"dev": ["--auto-open-devtools-for-tabs"],
110
"ci": ["--headless", "--no-sandbox"]
111
}
112
}
113
}
114
115
// Custom browser paths
116
{
117
"browser_paths": {
118
"Chrome": "/opt/google/chrome/chrome",
119
"Firefox": "/usr/local/firefox/firefox"
120
}
121
}
122
123
// Custom browser executables
124
{
125
"browser_exes": {
126
"Chromium": "chromium-browser",
127
"Chrome": "google-chrome-stable"
128
}
129
}
130
```
131
132
### Custom Launchers
133
134
Define custom launchers for specialized execution environments.
135
136
```javascript { .api }
137
interface CustomLauncher {
138
// Command Execution
139
command?: string; // Full command to execute
140
exe?: string; // Executable path
141
args?: string[]; // Command arguments
142
143
// Launcher Behavior
144
protocol?: 'browser' | 'tap' | 'process'; // Communication protocol
145
cwd?: string; // Working directory
146
env?: Record<string, string>; // Environment variables
147
148
// Display Options
149
hide_stdout?: boolean; // Hide standard output
150
}
151
```
152
153
**Usage Examples:**
154
155
```javascript
156
// Custom Node.js launcher
157
{
158
"launchers": {
159
"Node": {
160
"command": "node test/runner.js",
161
"protocol": "tap"
162
}
163
}
164
}
165
166
// Custom browser launcher
167
{
168
"launchers": {
169
"CustomChrome": {
170
"exe": "/path/to/chrome",
171
"args": [
172
"--user-data-dir=/tmp/chrome-test",
173
"--disable-extensions",
174
"<url>"
175
],
176
"protocol": "browser"
177
}
178
}
179
}
180
181
// Custom process launcher
182
{
183
"launchers": {
184
"Jest": {
185
"command": "npm run test:jest",
186
"protocol": "tap",
187
"cwd": "frontend/",
188
"env": {
189
"NODE_ENV": "test"
190
}
191
}
192
}
193
}
194
```
195
196
### Launcher Class API
197
198
Programmatic launcher control for advanced integrations.
199
200
```javascript { .api }
201
/**
202
* Base launcher class for controlling browser and process execution
203
*/
204
class Launcher {
205
/**
206
* Create a new launcher instance
207
* @param name - Launcher name
208
* @param settings - Launcher configuration
209
* @param config - Global configuration
210
*/
211
constructor(name: string, settings: CustomLauncher, config: Config);
212
213
/**
214
* Start the launcher
215
* @returns Promise that resolves when launcher starts
216
*/
217
start(): Promise<void>;
218
219
/**
220
* Kill the launcher process
221
* @returns Promise that resolves when launcher stops
222
*/
223
kill(): Promise<void>;
224
225
/**
226
* Check if this is a process launcher (not browser)
227
* @returns True if process launcher
228
*/
229
isProcess(): boolean;
230
231
/**
232
* Get the launcher protocol
233
* @returns Communication protocol
234
*/
235
protocol(): 'browser' | 'tap' | 'process';
236
237
/**
238
* Get the command line for this launcher
239
* @returns Command line string
240
*/
241
commandLine(): string;
242
}
243
```
244
245
### LauncherFactory Class
246
247
Factory for creating launcher instances with configuration.
248
249
```javascript { .api }
250
/**
251
* Factory for creating configured launcher instances
252
*/
253
class LauncherFactory {
254
/**
255
* Create a launcher factory
256
* @param name - Launcher name
257
* @param settings - Base launcher settings
258
* @param config - Global configuration
259
*/
260
constructor(name: string, settings: CustomLauncher, config: Config);
261
262
/**
263
* Create a launcher instance with additional options
264
* @param options - Additional launcher options
265
* @returns Configured launcher instance
266
*/
267
create(options?: Partial<CustomLauncher>): Launcher;
268
}
269
```
270
271
**Usage Examples:**
272
273
```javascript
274
const LauncherFactory = require('testem/lib/launcher-factory');
275
const Config = require('testem/lib/config');
276
277
// Create launcher factory
278
const config = new Config('dev');
279
const factory = new LauncherFactory('Chrome', {
280
exe: 'google-chrome',
281
protocol: 'browser'
282
}, config);
283
284
// Create launcher instances
285
const launcher1 = factory.create({
286
args: ['--incognito']
287
});
288
289
const launcher2 = factory.create({
290
args: ['--disable-plugins']
291
});
292
293
// Start launchers
294
launcher1.start().then(() => {
295
console.log('Chrome launcher 1 started');
296
});
297
```
298
299
## Browser-Specific Features
300
301
### Chrome/Chromium
302
303
```javascript
304
{
305
"browser_args": {
306
"Chrome": [
307
"--no-sandbox", // Disable sandbox (CI environments)
308
"--disable-gpu", // Disable GPU acceleration
309
"--disable-web-security", // Disable CORS (testing only)
310
"--disable-features=VizDisplayCompositor", // Disable compositor
311
"--auto-open-devtools-for-tabs", // Auto-open DevTools
312
"--incognito", // Incognito mode
313
"--headless" // Headless mode
314
]
315
}
316
}
317
```
318
319
### Firefox
320
321
```javascript
322
{
323
"browser_args": {
324
"Firefox": [
325
"--headless", // Headless mode
326
"--safe-mode", // Safe mode
327
"--devtools" // Open DevTools
328
]
329
}
330
}
331
```
332
333
### Safari
334
335
```javascript
336
{
337
"browser_args": {
338
"Safari": [
339
"--develop-menu", // Enable develop menu
340
"--javascript-enabled" // Ensure JavaScript is enabled
341
]
342
}
343
}
344
```
345
346
### Internet Explorer
347
348
```javascript
349
{
350
"browser_args": {
351
"IE": [
352
"-extoff", // Disable extensions
353
"-private" // Private browsing
354
]
355
}
356
}
357
```
358
359
## Process Launchers
360
361
### Node.js Launcher
362
363
```javascript
364
{
365
"launchers": {
366
"Node": {
367
"command": "node test/node-runner.js",
368
"protocol": "tap"
369
}
370
}
371
}
372
```
373
374
### Mocha Launcher
375
376
```javascript
377
{
378
"launchers": {
379
"Mocha": {
380
"command": "mocha test/**/*.js --reporter tap",
381
"protocol": "tap",
382
"hide_stdout": true
383
}
384
}
385
}
386
```
387
388
### Jest Launcher
389
390
```javascript
391
{
392
"launchers": {
393
"Jest": {
394
"command": "jest --testResultsProcessor=jest-tap-reporter",
395
"protocol": "tap"
396
}
397
}
398
}
399
```
400
401
## Advanced Launcher Configuration
402
403
### Conditional Launchers
404
405
```javascript
406
// testem.js - Dynamic launcher configuration
407
module.exports = {
408
launch_in_ci: function() {
409
const launchers = ['Chrome', 'Firefox'];
410
411
// Add Safari on macOS
412
if (process.platform === 'darwin') {
413
launchers.push('Safari');
414
}
415
416
// Add IE on Windows
417
if (process.platform === 'win32') {
418
launchers.push('IE');
419
}
420
421
return launchers;
422
}
423
};
424
```
425
426
### Environment-Specific Configuration
427
428
```javascript
429
{
430
"launchers": {
431
"TestNode": {
432
"command": "node --inspect test/runner.js",
433
"protocol": "tap",
434
"env": {
435
"NODE_ENV": "test",
436
"DEBUG": "app:*"
437
}
438
}
439
}
440
}
441
```
442
443
### Docker Launcher
444
445
```javascript
446
{
447
"launchers": {
448
"DockerChrome": {
449
"command": "docker run --rm -v $(pwd):/workspace selenium/standalone-chrome:latest",
450
"protocol": "browser"
451
}
452
}
453
}
454
```