{"id":19738275,"url":"https://github.com/httptoolkit/browser-launcher","last_synced_at":"2025-10-06T16:32:21.880Z","repository":{"id":41322475,"uuid":"185993636","full_name":"httptoolkit/browser-launcher","owner":"httptoolkit","description":"Detect the browser versions available on your system, and launch them in an isolated profile for automation \u0026 testing purposes.","archived":false,"fork":false,"pushed_at":"2024-04-10T13:37:32.000Z","size":504,"stargazers_count":20,"open_issues_count":1,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-01-15T04:48:45.769Z","etag":null,"topics":["browser-automation","browser-detection","browsers","testing","testing-tools"],"latest_commit_sha":null,"homepage":"https://httptoolkit.tech","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/httptoolkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2019-05-10T13:31:41.000Z","updated_at":"2025-01-07T22:41:52.000Z","dependencies_parsed_at":"2024-06-18T20:48:37.882Z","dependency_job_id":null,"html_url":"https://github.com/httptoolkit/browser-launcher","commit_stats":{"total_commits":312,"total_committers":27,"mean_commits":"11.555555555555555","dds":0.7788461538461539,"last_synced_commit":"ffcc04128d41276de742b2cc4fd4d45013738271"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fbrowser-launcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fbrowser-launcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fbrowser-launcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/httptoolkit%2Fbrowser-launcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/httptoolkit","download_url":"https://codeload.github.com/httptoolkit/browser-launcher/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234878730,"owners_count":18900681,"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":["browser-automation","browser-detection","browsers","testing","testing-tools"],"created_at":"2024-11-12T01:13:45.442Z","updated_at":"2025-10-06T16:32:21.530Z","avatar_url":"https://github.com/httptoolkit.png","language":"JavaScript","readme":"# browser-launcher[![Build Status](https://github.com/httptoolkit/browser-launcher/workflows/CI/badge.svg)](https://github.com/httptoolkit/browser-launcher/actions) [![Get it on npm](https://img.shields.io/npm/v/@httptoolkit/browser-launcher.svg)](https://www.npmjs.com/package/@httptoolkit/browser-launcher)\n\n\u003e _Part of [HTTP Toolkit](https://httptoolkit.com): powerful tools for building, testing \u0026 debugging HTTP(S)_\n\nDetect the browser versions available on your system and launch them in an isolated profile for automation \u0026 testing purposes.\n\nYou can launch browsers headlessly\n(using [Xvfb](http://en.wikipedia.org/wiki/Xvfb) or with [PhantomJS](http://phantomjs.org/)) and set the proxy\nconfiguration on the fly.\n\nThis project is the latest in a long series, each forked from the last:\n\n* [substack/browser-launcher](https://github.com/substack/browser-launcher)\n* [browser-launcher2](https://github.com/benderjs/browser-launcher2).\n* [james-proxy/james-browser-launcher](https://github.com/james-proxy/james-browser-launcher)\n\nEach previous versions seems to now be unmaintained, and this is a core component of [HTTP Toolkit](https://httptoolkit.com), so it's been forked here to ensure it can continue healthy into the future.\n\n## Supported browsers\n\nThe goal for this module is to support all major browsers on every desktop platform.\n\nAt the moment, `browser-launcher` supports following browsers on Windows, Unix and OS X:\n\n- Chrome\n- Chromium\n- Firefox\n- IE (Windows only)\n- Chromium-based Edge\n- Brave\n- Opera\n- Safari (Mac only)\n- PhantomJS\n- Arc (experimental, Mac only)\n\n## Setup\n\n### Quick usage\n\n```bash\n\u003e npx @httptoolkit/browser-launcher # Scans for browsers\n[\n    {\n        \"name\": \"chrome\",\n        \"version\": \"...\",\n        # ...\n    },\n    # ...\n]\n\n\u003e npx @httptoolkit/browser-launcher firefox # Launches a browser\nfirefox launched with PID: XXXXXX\n```\n\nIf the package is already installed locally, you can use `browser-launcher` to launch it directly instead, either from the `node_modules/.bin` directly, or as binary name with `npx`.\n\n### Install\n\n```\nnpm install @httptoolkit/browser-launcher\n```\n\n## Example\n\n### Browser launch\n\n```js\nconst launcher = require('@httptoolkit/browser-launcher');\n\nlauncher(function(err, launch) {\n\tif (err) {\n\t\treturn console.error(err);\n\t}\n\n\tlaunch('http://httptoolkit.com/', 'chrome', function(err, instance) {\n\t\tif (err) {\n\t\t\treturn console.error(err);\n\t\t}\n\n\t\tconsole.log('Instance started with PID:', instance.pid);\n\n\t\tinstance.on('stop', function(code) {\n\t\t\tconsole.log('Instance stopped with exit code:', code);\n\t\t});\n\t});\n});\n```\n\nOutputs:\n\n```\n$ node example/launch.js\nInstance started with PID: 12345\nInstance stopped with exit code: 0\n```\n\n### Browser launch with options\n\n```js\nvar launcher = require('@httptoolkit/browser-launcher');\n\nlauncher(function(err, launch) {\n\t// ...\n\tlaunch(\n\t\t'http://httptoolkit.com/',\n\t\t{\n\t\t\tbrowser: 'chrome',\n\t\t\tnoProxy: [ '127.0.0.1', 'localhost' ],\n\t\t\toptions: [\n\t\t\t\t'--disable-web-security',\n\t\t\t\t'--disable-extensions'\n\t\t\t]\n\t\t},\n\t\tfunction(err, instance) {\n\t\t\t// ...\n\t\t}\n\t);\n});\n```\n\n\n### Browser detection\n```js\nvar launcher = require('@httptoolkit/browser-launcher');\n\nlauncher.detect(function(available) {\n\tconsole.log('Available browsers:');\n\tconsole.dir(available);\n});\n```\n\nOutputs:\n\n```bash\n$ node example/detect.js\nAvailable browsers:\n[ { name: 'chrome',\n\t\tversion: '36.0.1985.125',\n\t\ttype: 'chrome',\n\t\tcommand: 'google-chrome' },\n\t{ name: 'chromium',\n\t\tversion: '36.0.1985.125',\n\t\ttype: 'chrome',\n\t\tcommand: 'chromium-browser' },\n\t{ name: 'firefox',\n\t\tversion: '31.0',\n\t\ttype: 'firefox',\n\t\tcommand: 'firefox' },\n\t{ name: 'phantomjs',\n\t\tversion: '1.9.7',\n\t\ttype: 'phantom',\n\t\tcommand: 'phantomjs' },\n\t{ name: 'opera',\n\t\tversion: '12.16',\n\t\ttype: 'opera',\n\t\tcommand: 'opera' } ]\n```\n\n### Detaching the launched browser process from your script\n\nIf you want the opened browser to remain open after killing your script, first, you need to set `options.detached` to `true` (see the API). By default, killing your script will kill the opened browsers.\n\nThen, if you want your script to immediately return control to the shell, you may additionally call `unref` on the `instance` object in the callback:\n\n```js\nvar launcher = require('@httptoolkit/browser-launcher');\nlauncher(function (err, launch) {\n\tlaunch('http://example.org/', {\n\t\tbrowser: 'chrome',\n\t\tdetached: true\n    }, function(err, instance) {\n\t\tif (err) {\n\t\t\treturn console.error(err);\n\t\t}\n\n\t\tinstance.process.unref();\n\t\tinstance.process.stdin.unref();\n\t\tinstance.process.stdout.unref();\n\t\tinstance.process.stderr.unref();\n\t});\n});\n```\n\n## API\n\n``` js\nvar launcher = require('@httptoolkit/browser-launcher');\n```\n\n### `launcher([configPath], callback)`\n\nDetect available browsers and pass `launch` function to the callback.\n\n**Parameters:**\n\n- *String* `configPath` - path to a browser configuration file *(Optional)*\n- *Function* `callback(err, launch)` - function called with `launch` function and errors (if any)\n\n### `launch(uri, options, callback)`\n\nOpen given URI in a browser and return an instance of it.\n\n**Parameters:**\n\n- *String* `uri` - URI to open in a newly started browser\n- *Object|String* `options` - configuration options or name of a browser to launch\n- *String* `options.browser` - name of a browser to launch\n- *String* `options.version` - version of a browser to launch, if none was given, the highest available version will be launched\n- *String* `options.proxy` - URI of the proxy server\n- *Array* `options.options` - additional command line options\n- *Boolean* `options.skipDefaults` - don't supply any default options to browser\n- *Boolean* `options.detached` - if true, then killing your script will not kill the opened browser\n- *Array|String* `options.noProxy` - An array of strings, containing proxy routes to skip over\n- *Boolean* `options.headless` - run a browser in a headless mode (only if **Xvfb** available)\n- *String|null* `options.profile` - path to a directory to use for the browser profile, overriding the default. Use `null` to force use of the default system profile (supported for Firefox \u0026 Chromium-based browsers only). Note that configuration options like `proxy` \u0026 `prefs` can't be used in Firefox with the default system profile.\n- *Function* `callback(err, instance)` - function fired when started a browser `instance` or an error occurred\n\n### `launch.browsers`\n\nThis property contains an array of all known and available browsers.\n\n### `instance`\n\nBrowser instance object.\n\n**Properties:**\n- *String* `command` - command used to start the instance\n- *Array* `args` - array of command line arguments used while starting the instance\n- *String* `image` - instance's image name\n- *String* `processName` - instance's process name\n- *Object* `process` - reference to instance's process started with Node's `child_process.spawn` API\n- *Number* `pid` - instance's process PID\n- *Stream* `stdout` - instance's process STDOUT stream\n- *Stream* `stderr` - instance's process STDERR stream\n\n**Events:**\n- `stop` - fired when instance stops\n\n**Methods:**\n- `stop(callback)` - stop the instance and fire the callback once stopped\n\n### `launcher.detect(callback)`\n\nDetects all browsers available.\n\n**Parameters:**\n- *Function* `callback(available)` - function called with array of all recognized browsers\n\nEach browser contains following properties:\n- `name` - name of a browser\n- `version` - browser's version\n- `type` - type of a browser i.e. browser's family\n- `command` - command used to launch a browser\n\n### `launcher.update([configFile], callback)`\n\nUpdates the browsers cache file (`~/.config/browser-launcher/config.json` is no `configFile` was given) and creates new profiles for found browsers.\n\n**Parameters:**\n- *String* `configFile` - path to the configuration file *Optional*\n- *Function* `callback(err, browsers)` - function called with found browsers and errors (if any)\n\n## Known Issues\n\n- IE8: after several starts and stops, if you manually open IE it will come up with a pop-up asking if we want to restore tabs (#21)\n- Chrome @ OSX: it's not possible to launch multiple instances of Chrome at once\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttptoolkit%2Fbrowser-launcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhttptoolkit%2Fbrowser-launcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttptoolkit%2Fbrowser-launcher/lists"}