0
# Karma Chrome Launcher
1

2
Karma Chrome Launcher is a Karma plugin that provides browser launchers for Chrome, Chrome Canary, Chromium, and Dartium browsers. It enables JavaScript testing in various Chrome-based browser environments including headless mode, making it essential for cross-browser testing workflows and continuous integration pipelines.
3

4
## Package Information
5

6
- **Package Name**: karma-chrome-launcher
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev karma-chrome-launcher`
10

11
## Core Imports
12

13
```javascript
14
// The package exports Karma DI modules, typically used via Karma configuration
15
const karmaChromeLauncher = require('karma-chrome-launcher');
16

17
// Or when installed as a plugin, Karma loads it automatically:
18
// plugins: ['karma-chrome-launcher']
19
```
20

21
## Basic Usage
22

23
```javascript
24
// karma.conf.js
25
module.exports = function(config) {
26
  config.set({
27
    // Basic browser configuration
28
    browsers: ['Chrome', 'ChromeHeadless'],
29
    
30
    // Custom launcher with flags
31
    customLaunchers: {
32
      Chrome_without_security: {
33
        base: 'Chrome',
34
        flags: ['--disable-web-security', '--disable-site-isolation-trials']
35
      },
36
      Chrome_with_debugging: {
37
        base: 'Chrome',
38
        chromeDataDir: path.resolve(__dirname, '.chrome')
39
      }
40
    },
41
    
42
    // Include the plugin
43
    plugins: [
44
      'karma-chrome-launcher',
45
      // other plugins...
46
    ]
47
  });
48
};
49
```
50

51
## Capabilities
52

53
### Browser Launchers
54

55
The package provides Karma dependency injection modules for launching different Chrome-based browsers.
56

57
```javascript { .api }
58
// Main module exports - Karma DI configuration object
59
module.exports = {
60
  'launcher:Chrome': ['type', ChromeBrowser],
61
  'launcher:ChromeHeadless': ['type', ChromeHeadlessBrowser], 
62
  'launcher:ChromeCanary': ['type', ChromeCanaryBrowser],
63
  'launcher:ChromeCanaryHeadless': ['type', ChromeCanaryHeadlessBrowser],
64
  'launcher:Chromium': ['type', ChromiumBrowser],
65
  'launcher:ChromiumHeadless': ['type', ChromiumHeadlessBrowser],
66
  'launcher:Dartium': ['type', DartiumBrowser]
67
};
68
```
69

70
Each launcher supports the following configuration options:
71

72
```javascript { .api }
73
interface LauncherArgs {
74
  /** Array of command-line flags to pass to the browser */
75
  flags?: string[];
76
  /** Custom Chrome user data directory path (overrides default temp directory) */
77
  chromeDataDir?: string;
78
}
79

80
/** Browser launcher constructor function signature */
81
type BrowserLauncher = (baseBrowserDecorator: Function, args: LauncherArgs) => void;
82

83
/** Browser launcher prototype with required properties */
84
interface BrowserPrototype {
85
  /** Browser name identifier */
86
  name: string;
87
  /** Platform-specific default command paths */
88
  DEFAULT_CMD: {
89
    linux?: string | null;
90
    darwin?: string | null;
91
    win32?: string | null;
92
  };
93
  /** Environment variable name for binary path override */
94
  ENV_CMD: string;
95
  /** Internal method to generate browser command-line options */
96
  _getOptions(url: string): string[];
97
}
98
```
99

100
### Chrome Browser
101

102
Standard Chrome browser launcher for desktop testing.
103

104
```javascript { .api }
105
// Used in Karma configuration
106
browsers: ['Chrome']
107

108
// Environment variable override
109
CHROME_BIN=/path/to/chrome karma start
110
```
111

112
**Platform Support:**
113
- **Linux**: Searches for `google-chrome` or `google-chrome-stable`
114
- **macOS**: Uses `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
115
- **Windows**: Searches Chrome installation directories
116

117
**Default Flags Added:**
118
Chrome automatically adds these flags to all instances:
119
```
120
--user-data-dir=<temp-dir>
121
--enable-automation
122
--no-default-browser-check
123
--no-first-run
124
--disable-default-apps
125
--disable-popup-blocking
126
--disable-translate
127
--disable-background-timer-throttling
128
--disable-renderer-backgrounding
129
--disable-device-discovery-notifications
130
```
131

132
### Chrome Headless Browser
133

134
Chrome browser in headless mode for CI/CD environments.
135

136
```javascript { .api }
137
// Used in Karma configuration  
138
browsers: ['ChromeHeadless']
139

140
// Automatically adds headless flags:
141
// --headless, --disable-gpu, --disable-dev-shm-usage
142
// --remote-debugging-port=9222 (if not already specified)
143
```
144

145
### Chrome Canary Browser
146

147
Chrome Canary browser launcher for testing with bleeding-edge Chrome features.
148

149
```javascript { .api }
150
// Used in Karma configuration
151
browsers: ['ChromeCanary']
152

153
// Environment variable override  
154
CHROME_CANARY_BIN=/path/to/chrome-canary karma start
155

156
// Automatically adds performance flags:
157
// --js-flags=--nocrankshaft --noopt
158
```
159

160
### Chrome Canary Headless Browser
161

162
Chrome Canary browser in headless mode.
163

164
```javascript { .api }
165
// Used in Karma configuration
166
browsers: ['ChromeCanaryHeadless']
167
```
168

169
### Chromium Browser
170

171
Open-source Chromium browser launcher.
172

173
```javascript { .api }
174
// Used in Karma configuration
175
browsers: ['Chromium']
176

177
// Environment variable override
178
CHROMIUM_BIN=/path/to/chromium karma start
179
```
180

181
**Platform Support:**
182
- **Linux**: Searches for `chromium-browser` or `chromium`
183
- **macOS**: Uses `/Applications/Chromium.app/Contents/MacOS/Chromium`
184
- **Windows**: Searches Chromium installation directories
185

186
**Default Flags Added:**
187
Chromium automatically adds these flags to all instances:
188
```
189
--user-data-dir=<temp-dir>
190
--no-default-browser-check
191
--no-first-run
192
--disable-default-apps
193
--disable-popup-blocking
194
--disable-translate
195
--disable-background-timer-throttling
196
```
197

198
**Note:** Chromium does not include the `--enable-automation`, `--disable-renderer-backgrounding`, and `--disable-device-discovery-notifications` flags that Chrome includes.
199

200
### Chromium Headless Browser
201

202
Chromium browser in headless mode.
203

204
```javascript { .api }
205
// Used in Karma configuration
206
browsers: ['ChromiumHeadless']
207
```
208

209
### Dartium Browser (Deprecated)
210

211
Legacy Dartium browser launcher for Dart applications. **Note: Dartium is obsolete as Dart web development now uses standard browsers.**
212

213
```javascript { .api }
214
// Used in Karma configuration
215
browsers: ['Dartium']
216

217
// Environment variable override
218
DARTIUM_BIN=/path/to/dartium karma start
219
```
220

221
## Configuration Examples
222

223
### Custom Flags
224

225
```javascript
226
// karma.conf.js
227
customLaunchers: {
228
  Chrome_without_security: {
229
    base: 'Chrome',
230
    flags: [
231
      '--disable-web-security',
232
      '--disable-site-isolation-trials',
233
      '--allow-running-insecure-content'
234
    ]
235
  }
236
}
237
```
238

239
### Custom User Data Directory
240

241
```javascript
242
// karma.conf.js
243
const path = require('path');
244

245
customLaunchers: {
246
  Chrome_with_debugging: {
247
    base: 'Chrome',
248
    chromeDataDir: path.resolve(__dirname, '.chrome')
249
  }
250
}
251
```
252

253
### JavaScript Flags
254

255
The launcher provides special handling for `--js-flags` parameters:
256

257
```javascript
258
customLaunchers: {
259
  Chrome_with_js_flags: {
260
    base: 'Chrome',
261
    flags: ['--js-flags="--expose-gc --harmony"']
262
  }
263
}
264
```
265

266
### Puppeteer Integration
267

268
```javascript
269
// karma.conf.js
270
process.env.CHROME_BIN = require('puppeteer').executablePath();
271

272
module.exports = function(config) {
273
  config.set({
274
    browsers: ['ChromeHeadless']
275
  });
276
};
277
```
278

279
## Test Utilities
280

281
The package also exports test utilities for internal function testing:
282

283
```javascript { .api }
284
// Available on module.exports.test
285
const testUtils = require('karma-chrome-launcher').test;
286

287
/**
288
 * Check if a flag is a JS flags parameter
289
 * @param {string} flag - Command line flag to check
290
 * @returns {boolean} True if flag starts with --js-flags=
291
 */
292
function isJSFlags(flag);
293

294
/**
295
 * Sanitize JS flags by removing quotes
296
 * @param {string} flag - JS flags parameter to sanitize
297
 * @returns {string} Sanitized flag without quotes
298
 */
299
function sanitizeJSFlags(flag);
300

301
/**
302
 * Generate headless browser options
303
 * @param {string} url - Target URL
304
 * @param {object} args - Launcher arguments
305
 * @param {function} parent - Parent options function
306
 * @returns {string[]} Array of command line options
307
 */
308
function headlessGetOptions(url, args, parent);
309

310
/**
311
 * Generate Chrome Canary browser options  
312
 * @param {string} url - Target URL
313
 * @param {object} args - Launcher arguments
314
 * @param {function} parent - Parent options function
315
 * @returns {string[]} Array of command line options
316
 */
317
function canaryGetOptions(url, args, parent);
318
```
319

320
## Browser Detection
321

322
The package automatically detects browser installations using platform-specific logic:
323

324
```javascript { .api }
325
/**
326
 * Get Chrome executable path on Windows
327
 * @param {string} chromeDirName - Chrome directory name ('Chrome' or 'Chrome SxS')
328
 * @returns {string|null} Path to chrome.exe or null if not found
329
 */
330
function getChromeExe(chromeDirName);
331

332
/**
333
 * Get Chromium executable path on Windows  
334
 * @returns {string|null} Path to chromium chrome.exe or null if not found
335
 */
336
function getChromiumExe();
337

338
/**
339
 * Find binary using which command on Linux
340
 * @param {string[]} commands - Array of command names to search for
341
 * @returns {string|null} First found command or null
342
 */
343
function getBin(commands);
344

345
/**
346
 * Get Chrome path on macOS with user directory fallback
347
 * @param {string} defaultPath - Default application path
348
 * @returns {string} Resolved Chrome path
349
 */
350
function getChromeDarwin(defaultPath);
351
```
352

353
### Windows Detection
354
- Searches environment variables: `LOCALAPPDATA`, `PROGRAMFILES`, `PROGRAMFILES(X86)`, `ProgramW6432`
355
- Chrome path: `<ENV_VAR>\Google\<ChromeDirName>\Application\chrome.exe`
356
  - Regular Chrome uses directory name `Chrome`
357
  - Chrome Canary uses directory name `Chrome SxS`
358
- Chromium path: `<ENV_VAR>\Chromium\Application\chrome.exe`
359

360
### Linux Detection  
361
- Uses the `which` command to find executables in PATH
362
- Chrome: searches for `google-chrome`, `google-chrome-stable`
363
- Chrome Canary: searches for `google-chrome-canary`, `google-chrome-unstable`
364
- Chromium: searches for `chromium-browser`, `chromium` (prioritizes `chromium-browser` to avoid conflict with legacy `chromium-bsu` package)
365

366
### macOS Detection
367
- Uses hardcoded application paths with user home directory fallbacks
368
- Chrome: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
369
  - Fallback: `$HOME/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
370
- Chrome Canary: `/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary`
371
  - Fallback: `$HOME/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary`
372
- Chromium: `/Applications/Chromium.app/Contents/MacOS/Chromium`
373

374
## Dependencies
375

376
- **which**: "^1.2.1" - Used to locate browser executables on Linux platforms