1.1.1 • Published 9 days ago

chrome-launcher v1.1.1

Weekly downloads
778,878
License
Apache-2.0
Repository
github
Last release
9 days ago

Chrome Launcher GitHub Actions Status Badge NPM chrome-launcher package

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

yarn add chrome-launcher

# or with npm:
npm install chrome-launcher

API

.launch([opts])

Launch options

{
  // (optional) remote debugging port number to use. If provided port is already busy, launch() will reject
  // Default: an available port is autoselected
  port: number;

  // (optional) When `port` is specified *and* no Chrome is found at that port,
  // * if `false` (default), chrome-launcher will launch a new Chrome with that port.
  // * if `true`, throw an error
  // This option is useful when you wish to explicitly connect to a running Chrome, such as on a mobile device via adb
  // Default: false
  portStrictMode: boolean;

  // (optional) Additional flags to pass to Chrome, for example: ['--headless', '--disable-gpu']
  // See: https://github.com/GoogleChrome/chrome-launcher/blob/main/docs/chrome-flags-for-tools.md
  // Do note, many flags are set by default: https://github.com/GoogleChrome/chrome-launcher/blob/main/src/flags.ts
  chromeFlags: Array<string>;

  // (optional) Additional preferences to be set in Chrome, for example: {'download.default_directory': __dirname}
  // See: https://chromium.googlesource.com/chromium/src/+/main/chrome/common/pref_names.cc
  // Do note, if you set preferences when using your default profile it will overwrite these
  prefs: {[key: string]: Object};

  // (optional) Close the Chrome process on `Ctrl-C`
  // Default: true
  handleSIGINT: boolean;

  // (optional) Explicit path of intended Chrome binary
  // * If this `chromePath` option is defined, it will be used.
  // * Otherwise, the `CHROME_PATH` env variable will be used if set. (`LIGHTHOUSE_CHROMIUM_PATH` is deprecated)
  // * Otherwise, a detected Chrome Canary will be used if found
  // * Otherwise, a detected Chrome (stable) will be used
  chromePath: string;

  // (optional) Chrome profile path to use, if set to `false` then the default profile will be used.
  // By default, a fresh Chrome profile will be created
  userDataDir: string | boolean;

  // (optional) Starting URL to open the browser with
  // Default: `about:blank`
  startingUrl: string;

  // (optional) Logging level
  // Default: 'silent'
  logLevel: 'verbose'|'info'|'error'|'silent';

  // (optional) Flags specific in [flags.ts](src/flags.ts) will not be included.
  // Typically used with the defaultFlags() method and chromeFlags option.
  // Default: false
  ignoreDefaultFlags: boolean;

  // (optional) Interval in ms, which defines how often launcher checks browser port to be ready.
  // Default: 500
  connectionPollInterval: number;

  // (optional) A number of retries, before browser launch considered unsuccessful.
  // Default: 50
  maxConnectionRetries: number;

  // (optional) A dict of environmental key value pairs to pass to the spawned chrome process.
  envVars: {[key: string]: string};
};

Launched chrome interface

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

// The remote debugging port exposed by the launched chrome
chrome.port: number;

// Method to kill Chrome (and cleanup the profile folder)
chrome.kill: () => Promise<void>;

// The process id
chrome.pid: number;

// The childProcess object for the launched Chrome
chrome.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.

import * as ChromeLauncher from 'chrome-launcher';

async function cleanup() {
  await ChromeLauncher.killAll();
}

Examples

Launching chrome:

import * as ChromeLauncher from 'chrome-launcher';

ChromeLauncher.launch({
  startingUrl: 'https://google.com'
}).then(chrome => {
  console.log(`Chrome debugging port running on ${chrome.port}`);
});

Launching headless chrome:

import * as ChromeLauncher from 'chrome-launcher';

ChromeLauncher.launch({
  startingUrl: 'https://google.com',
  chromeFlags: ['--headless', '--disable-gpu']
}).then(chrome => {
  console.log(`Chrome debugging port running on ${chrome.port}`);
});

Launching with support for extensions and audio:

import * as ChromeLauncher from 'chrome-launcher';

const newFlags = ChromeLauncher.Launcher.defaultFlags().filter(flag => flag !== '--disable-extensions' && flag !== '--mute-audio');

ChromeLauncher.launch({
  ignoreDefaultFlags: true,
  chromeFlags: newFlags,
}).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:

language: node_js
install:
  - yarn install
before_script:
  - export DISPLAY=:99.0
  - export CHROME_PATH="$(pwd)/chrome-linux/chrome"
  - sh -e /etc/init.d/xvfb start
  - sleep 3 # wait for xvfb to boot

addons:
  chrome: stable
eog_seog_xxchrome-headlessnative-stream-wa-automateeufa@floms-inc/response-raideroxygenidedebug-visualizerwits-for-testwits-for-test-1wits-for-test-3wits-for-test-betawits-test1wits-test14wits-test2wits-test20wits-test3wits-test5wits-test55wits-test7@tizentv/witstestwits-beta-testsourcemap-wizard@tizentv/testrprovider-debuggerwooooosikwooooosik11wooooosik12wooooosik13wooooosik5wooooosik7wooooosik8@tizentv/testmodule@s2click/venomlighthouse-loacalelmenoufi-api-whatswinraderapi_whats_elmenoufiwebpack-open-chrome-extension@joaosouz4/venom-bot@mayahq/wabornsrobot-serversrobot-basics@toptal/lhci-cli@etiennemartin/lighthouse-ciphotomnemonic-epmarvolo-botmarvolo-upchromecors@rustmeta/rustplus-tsgympass-tokengoogle-reverse-image-searchlighthouse@everything-registry/sub-chunk-1324jawwy-sdkreact-native-credit-card-pkglux-ai-vis@andrewyan/lighthouse-statistic@angga30prabu/wa-modified@arturnpm/npmregisterbbresque@articulate/chromeless@29ways/fewtbinance-pump-botbhavyasoftberliozbitou-cli@cocreate/lighthouse@codechecks/lighthouse-keepercloudflare-scrapercli-statistics-lighthousecollect-react-statsblockly-flux-back@cybernaut/chrome@daveholst/loki-target-chrome-app@deogle/ballista@bjacobel/perfbrs_lighthouse@bes/shot@bowtie/lighthousecal-scrapecamel-route-viewer-backbugout-launcher@blusalt-sdk/react-native-blusalt-document-verificationbundle-wizardblueimp-mocha-chrome@bordertech/lighthouse-cicarnage-bot@cb-stimmer/chaturbate-browser@gemini-testing/devtoolsthai-library-react-component-corejawy_library_v1gamification-jawwy-libraryoffia-chromepsikuspwa-asset-generatorpwa-asset-generator-fix-chromiumrainstorm-lightpwmetricspuppeteer-real-browser
1.1.1

9 days ago

1.1.0

6 months ago

1.0.0

8 months ago

0.15.2

12 months ago

0.15.1

2 years ago

0.15.0

2 years ago

0.14.2

2 years ago

0.14.1

2 years ago

0.14.0

3 years ago

0.13.4

4 years ago

0.13.3

4 years ago

0.13.2

4 years ago

0.13.1

4 years ago

0.13.0

4 years ago

0.12.0

4 years ago

0.11.2

5 years ago

0.11.1

5 years ago

0.11.0

5 years ago

0.10.7

5 years ago

0.10.6

5 years ago

0.10.5

6 years ago

0.10.4

6 years ago

0.10.3

6 years ago

0.10.2

6 years ago

0.10.1

6 years ago

0.10.0

6 years ago

0.9.0

6 years ago

0.8.1

6 years ago

0.8.0

7 years ago

0.7.0

7 years ago

0.6.0

7 years ago

0.5.0

7 years ago

0.4.0

7 years ago

0.3.2

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.1

7 years ago

0.2.0

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.0.1

7 years ago