Chrome Launcher

Launch Google Chrome with ease from node.

• Disables many Chrome services that add noise to automated scenarios
• Opens up the browser's remote-debugging-port on an available port
• Automagically locates a Chrome binary to launch
• Uses a fresh Chrome profile for each launch, and cleans itself up on kill()
• Binds Ctrl-C (by default) to terminate the Chrome process
• Exposes a small set of options for configurability over these details

Once launched, interacting with the browser must be done over the devtools protocol, typically via chrome-remote-interface. For many cases Puppeteer is recommended, though it has its own chrome launching mechanism.

Installing

1yarn add chrome-launcher
2
3# or with npm:
4npm install chrome-launcher

API

.launch([opts])

Launch options

1{
2  // (optional) remote debugging port number to use. If provided port is already busy, launch() will reject
3  // Default: an available port is autoselected
4  port: number;
5
6  // (optional) When `port` is specified *and* no Chrome is found at that port,
7  // * if `false` (default), chrome-launcher will launch a new Chrome with that port.
8  // * if `true`, throw an error
9  // This option is useful when you wish to explicitly connect to a running Chrome, such as on a mobile device via adb
10  // Default: false
11  portStrictMode: boolean;
12
13  // (optional) Additional flags to pass to Chrome, for example: ['--headless', '--disable-gpu']
14  // See: https://github.com/GoogleChrome/chrome-launcher/blob/main/docs/chrome-flags-for-tools.md
15  // Do note, many flags are set by default: https://github.com/GoogleChrome/chrome-launcher/blob/main/src/flags.ts
16  chromeFlags: Array<string>;
17
18  // (optional) Additional preferences to be set in Chrome, for example: {'download.default_directory': __dirname}
19  // See: https://chromium.googlesource.com/chromium/src/+/main/chrome/common/pref_names.cc
20  // Do note, if you set preferences when using your default profile it will overwrite these
21  prefs: {[key: string]: Object};
22
23  // (optional) Close the Chrome process on `Ctrl-C`
24  // Default: true
25  handleSIGINT: boolean;
26
27  // (optional) Explicit path of intended Chrome binary
28  // * If this `chromePath` option is defined, it will be used.
29  // * Otherwise, the `CHROME_PATH` env variable will be used if set. (`LIGHTHOUSE_CHROMIUM_PATH` is deprecated)
30  // * Otherwise, a detected Chrome Canary will be used if found
31  // * Otherwise, a detected Chrome (stable) will be used
32  chromePath: string;
33
34  // (optional) Chrome profile path to use, if set to `false` then the default profile will be used.
35  // By default, a fresh Chrome profile will be created
36  userDataDir: string | boolean;
37
38  // (optional) Starting URL to open the browser with
39  // Default: `about:blank`
40  startingUrl: string;
41
42  // (optional) Logging level
43  // Default: 'silent'
44  logLevel: 'verbose'|'info'|'error'|'silent';
45
46  // (optional) Flags specific in [flags.ts](src/flags.ts) will not be included.
47  // Typically used with the defaultFlags() method and chromeFlags option.
48  // Default: false
49  ignoreDefaultFlags: boolean;
50
51  // (optional) Interval in ms, which defines how often launcher checks browser port to be ready.
52  // Default: 500
53  connectionPollInterval: number;
54
55  // (optional) A number of retries, before browser launch considered unsuccessful.
56  // Default: 50
57  maxConnectionRetries: number;
58
59  // (optional) A dict of environmental key value pairs to pass to the spawned chrome process.
60  envVars: {[key: string]: string};
61};

Launched chrome interface

.launch().then(chrome => ...

1// The remote debugging port exposed by the launched chrome
2chrome.port: number;
3
4// Method to kill Chrome (and cleanup the profile folder)
5chrome.kill: () => Promise<void>;
6
7// The process id
8chrome.pid: number;
9
10// The childProcess object for the launched Chrome
11chrome.process: childProcess

ChromeLauncher.Launcher.defaultFlags()

Returns an Array<string> of the default flags Chrome is launched with. Typically used along with the ignoreDefaultFlags and chromeFlags options.

Note: This array will exclude the following flags: --remote-debugging-port --disable-setuid-sandbox --user-data-dir.

ChromeLauncher.Launcher.getInstallations()

Returns an Array<string> of paths to available Chrome installations. When chromePath is not provided to .launch(), the first installation returned from this method is used instead.

Note: This method performs synchronous I/O operations.

.killAll()

Attempts to kill all Chrome instances created with .launch([opts]). Returns a Promise that resolves to an array of errors that occurred while killing instances. If all instances were killed successfully, the array will be empty.

1import * as ChromeLauncher from 'chrome-launcher';
2
3async function cleanup() {
4  await ChromeLauncher.killAll();
5}

Examples

Launching chrome:

1import * as ChromeLauncher from 'chrome-launcher';
2
3ChromeLauncher.launch({
4  startingUrl: 'https://google.com'
5}).then(chrome => {
6  console.log(`Chrome debugging port running on ${chrome.port}`);
7});

Launching headless chrome:

1import * as ChromeLauncher from 'chrome-launcher';
2
3ChromeLauncher.launch({
4  startingUrl: 'https://google.com',
5  chromeFlags: ['--headless', '--disable-gpu']
6}).then(chrome => {
7  console.log(`Chrome debugging port running on ${chrome.port}`);
8});

Launching with support for extensions and audio:

1import * as ChromeLauncher from 'chrome-launcher';
2
3const newFlags = ChromeLauncher.Launcher.defaultFlags().filter(flag => flag !== '--disable-extensions' && flag !== '--mute-audio');
4
5ChromeLauncher.launch({
6  ignoreDefaultFlags: true,
7  chromeFlags: newFlags,
8}).then(chrome => { ... });

Continuous Integration

In a CI environment like Travis, Chrome may not be installed. If you want to use chrome-launcher, Travis can install Chrome at run time with an addon. Alternatively, you can also install Chrome using the download-chrome.sh script.

Then in .travis.yml, use it like so:

1language: node_js
2install:
3  - yarn install
4before_script:
5  - export DISPLAY=:99.0
6  - export CHROME_PATH="$(pwd)/chrome-linux/chrome"
7  - sh -e /etc/init.d/xvfb start
8  - sleep 3 # wait for xvfb to boot
9
10addons:
11  chrome: stable