{"id":13485043,"url":"https://github.com/GoogleChrome/chrome-launcher","last_synced_at":"2025-03-27T17:30:46.446Z","repository":{"id":24517653,"uuid":"101809442","full_name":"GoogleChrome/chrome-launcher","owner":"GoogleChrome","description":"Launch Google Chrome with ease from node.","archived":false,"fork":false,"pushed_at":"2024-09-11T21:36:33.000Z","size":16125,"stargazers_count":1248,"open_issues_count":83,"forks_count":188,"subscribers_count":43,"default_branch":"main","last_synced_at":"2024-10-29T10:23:44.063Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/chrome-launcher","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleChrome.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-29T21:44:00.000Z","updated_at":"2024-10-28T12:35:46.000Z","dependencies_parsed_at":"2024-01-26T13:08:39.701Z","dependency_job_id":"551bbe63-93c6-4f21-bb1a-637fb3c238b7","html_url":"https://github.com/GoogleChrome/chrome-launcher","commit_stats":{"total_commits":263,"total_committers":64,"mean_commits":4.109375,"dds":0.6692015209125475,"last_synced_commit":"d6be1f3250ef7ff7648ae58c4e92e48509bdbe7c"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChrome%2Fchrome-launcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChrome%2Fchrome-launcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChrome%2Fchrome-launcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleChrome%2Fchrome-launcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleChrome","download_url":"https://codeload.github.com/GoogleChrome/chrome-launcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245516791,"owners_count":20628227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:43.683Z","updated_at":"2025-03-27T17:30:45.636Z","avatar_url":"https://github.com/GoogleChrome.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Chrome Launcher [![GitHub Actions Status Badge](https://github.com/GoogleChrome/chrome-launcher/workflows/🛠/badge.svg)](https://github.com/GoogleChrome/chrome-launcher/actions) [![NPM chrome-launcher package](https://img.shields.io/npm/v/chrome-launcher.svg)](https://npmjs.org/package/chrome-launcher)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/39191/29847271-a7ba82f8-8ccf-11e7-8d54-eb88fdf0b6d0.png\" align=right height=200\u003e\n\nLaunch Google Chrome with ease from node.\n\n* [Disables many Chrome services](https://github.com/GoogleChrome/chrome-launcher/blob/main/src/flags.ts) that add noise to automated scenarios\n* Opens up the browser's `remote-debugging-port` on an available port\n* Automagically locates a Chrome binary to launch\n* Uses a fresh Chrome profile for each launch, and cleans itself up on `kill()`\n* Binds `Ctrl-C` (by default) to terminate the Chrome process\n* Exposes a small set of [options](#api) for configurability over these details\n\nOnce launched, interacting with the browser must be done over the [devtools protocol](https://chromedevtools.github.io/devtools-protocol/), typically via [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface/). For many cases [Puppeteer](https://github.com/GoogleChrome/puppeteer) is recommended, though it has its own chrome launching mechanism.\n\n### Installing\n\n```sh\nyarn add chrome-launcher\n\n# or with npm:\nnpm install chrome-launcher\n```\n\n\n## API\n\n### `.launch([opts])`\n\n#### Launch options\n\n```js\n{\n  // (optional) remote debugging port number to use. If provided port is already busy, launch() will reject\n  // Default: an available port is autoselected\n  port: number;\n\n  // (optional) When `port` is specified *and* no Chrome is found at that port,\n  // * if `false` (default), chrome-launcher will launch a new Chrome with that port.\n  // * if `true`, throw an error\n  // This option is useful when you wish to explicitly connect to a running Chrome, such as on a mobile device via adb\n  // Default: false\n  portStrictMode: boolean;\n\n  // (optional) Additional flags to pass to Chrome, for example: ['--headless', '--disable-gpu']\n  // See: https://github.com/GoogleChrome/chrome-launcher/blob/main/docs/chrome-flags-for-tools.md\n  // Do note, many flags are set by default: https://github.com/GoogleChrome/chrome-launcher/blob/main/src/flags.ts\n  chromeFlags: Array\u003cstring\u003e;\n\n  // (optional) Additional preferences to be set in Chrome, for example: {'download.default_directory': __dirname}\n  // See: https://chromium.googlesource.com/chromium/src/+/main/chrome/common/pref_names.cc\n  // Do note, if you set preferences when using your default profile it will overwrite these\n  prefs: {[key: string]: Object};\n\n  // (optional) Close the Chrome process on `Ctrl-C`\n  // Default: true\n  handleSIGINT: boolean;\n\n  // (optional) Explicit path of intended Chrome binary\n  // * If this `chromePath` option is defined, it will be used.\n  // * Otherwise, the `CHROME_PATH` env variable will be used if set. (`LIGHTHOUSE_CHROMIUM_PATH` is deprecated)\n  // * Otherwise, a detected Chrome Canary will be used if found\n  // * Otherwise, a detected Chrome (stable) will be used\n  chromePath: string;\n\n  // (optional) Chrome profile path to use, if set to `false` then the default profile will be used.\n  // By default, a fresh Chrome profile will be created\n  userDataDir: string | boolean;\n\n  // (optional) Starting URL to open the browser with\n  // Default: `about:blank`\n  startingUrl: string;\n\n  // (optional) Logging level\n  // Default: 'silent'\n  logLevel: 'verbose'|'info'|'error'|'silent';\n\n  // (optional) Flags specific in [flags.ts](src/flags.ts) will not be included.\n  // Typically used with the defaultFlags() method and chromeFlags option.\n  // Default: false\n  ignoreDefaultFlags: boolean;\n\n  // (optional) Interval in ms, which defines how often launcher checks browser port to be ready.\n  // Default: 500\n  connectionPollInterval: number;\n\n  // (optional) A number of retries, before browser launch considered unsuccessful.\n  // Default: 50\n  maxConnectionRetries: number;\n\n  // (optional) A dict of environmental key value pairs to pass to the spawned chrome process.\n  envVars: {[key: string]: string};\n};\n```\n\n#### Launched chrome interface\n\n#### `.launch().then(chrome =\u003e ...`\n\n```js\n// The remote debugging port exposed by the launched chrome\nchrome.port: number;\n\n// Method to kill Chrome (and cleanup the profile folder)\nchrome.kill: () =\u003e Promise\u003cvoid\u003e;\n\n// The process id\nchrome.pid: number;\n\n// The childProcess object for the launched Chrome\nchrome.process: childProcess\n```\n\n### `ChromeLauncher.Launcher.defaultFlags()`\n\nReturns an `Array\u003cstring\u003e` of the default [flags](docs/chrome-flags-for-tools.md) Chrome is launched with. Typically used along with the `ignoreDefaultFlags` and `chromeFlags` options.\n\nNote: This array will exclude the following flags: `--remote-debugging-port` `--disable-setuid-sandbox` `--user-data-dir`.\n\n### `ChromeLauncher.Launcher.getInstallations()`\n\nReturns an `Array\u003cstring\u003e` of paths to available Chrome installations. When `chromePath` is not provided to `.launch()`, the first installation returned from this method is used instead.\n\nNote: This method performs synchronous I/O operations.\n\n### `.killAll()`\n\nAttempts to kill all Chrome instances created with [`.launch([opts])`](#launchopts). 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.\n\n```js\nimport * as ChromeLauncher from 'chrome-launcher';\n\nasync function cleanup() {\n  await ChromeLauncher.killAll();\n}\n```\n\n## Examples\n\n#### Launching chrome:\n\n```js\nimport * as ChromeLauncher from 'chrome-launcher';\n\nChromeLauncher.launch({\n  startingUrl: 'https://google.com'\n}).then(chrome =\u003e {\n  console.log(`Chrome debugging port running on ${chrome.port}`);\n});\n```\n\n\n#### Launching headless chrome:\n\n```js\nimport * as ChromeLauncher from 'chrome-launcher';\n\nChromeLauncher.launch({\n  startingUrl: 'https://google.com',\n  chromeFlags: ['--headless', '--disable-gpu']\n}).then(chrome =\u003e {\n  console.log(`Chrome debugging port running on ${chrome.port}`);\n});\n```\n\n#### Launching with support for extensions and audio:\n\n```js\nimport * as ChromeLauncher from 'chrome-launcher';\n\nconst newFlags = ChromeLauncher.Launcher.defaultFlags().filter(flag =\u003e flag !== '--disable-extensions' \u0026\u0026 flag !== '--mute-audio');\n\nChromeLauncher.launch({\n  ignoreDefaultFlags: true,\n  chromeFlags: newFlags,\n}).then(chrome =\u003e { ... });\n```\n\n### Continuous Integration\n\nIn 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](https://docs.travis-ci.com/user/chrome).  Alternatively, you can also install Chrome using the [`download-chrome.sh`](https://raw.githubusercontent.com/GoogleChrome/chrome-launcher/v0.8.0/scripts/download-chrome.sh) script.\n\nThen in `.travis.yml`, use it like so:\n\n```yaml\nlanguage: node_js\ninstall:\n  - yarn install\nbefore_script:\n  - export DISPLAY=:99.0\n  - export CHROME_PATH=\"$(pwd)/chrome-linux/chrome\"\n  - sh -e /etc/init.d/xvfb start\n  - sleep 3 # wait for xvfb to boot\n\naddons:\n  chrome: stable\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleChrome%2Fchrome-launcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGoogleChrome%2Fchrome-launcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGoogleChrome%2Fchrome-launcher/lists"}