the-last-browser-launcher

Detect the browsers installed on your system and launch them in an isolated profile for automation & testing purposes. Supports Linux, Mac and Windows.

This project is the latest in a long series, each forked from the last:

• substack/browser-launcher (lightly maintained)
• benderjs/browser-launcher2 (unmaintained).
• james-proxy/james-browser-launcher (unmaintained)
• httptoolkit/browser-launcher (actively maintained)

They all have their problems. This fork is temporary, meant to consolidate fixes and reduce API surface, after which it will be split up into small, community-owned modules. In other words, this fork exists so that the project can die a good death. Its API is subject to change without warning.

Supported browsers

• Chrome
• Chromium
• Firefox
• IE (Windows only)
• Chromium-based Edge (Windows & Mac only)
• Brave
• Opera
• Safari

Install

npm install the-last-browser-launcher

Example

Browser launch

const launcher = require('the-last-browser-launcher')

launcher.detect(function(err, manifests) {
  if (err) throw err

  launcher.launch(manifests[0], 'http://example.com/', function(err, instance) {
    if (err) throw err

    console.log('Instance started with PID:', instance.pid)

    instance.on('stop', function(code) {
      console.log('Instance stopped with exit code:', code)
    })
  })
})

Outputs:

$ node example/launch.js
Instance started with PID: 12345
Instance stopped with exit code: 0

API

const launcher = require('the-last-browser-launcher')

launcher.detect(callback)

Get available browsers.

Parameters:

• Function callback(err, manifests)

launcher.launch(manifest, uri[, options], callback)

Open given URI in a browser and yield an instance of it.

Parameters:

• Object manifest - A manifest from detect()
• String uri - URI to open in a newly started browser
• Object options:
  • String proxy - URI of the proxy server
  • Array args - additional command line arguments
  • Boolean skipDefaults - don't supply any default args to browser
  • Boolean detached - if true, then killing your script will not kill the opened browser
  • Array|String noProxy - An array of strings, containing proxy routes to skip over
  • Boolean headless - run in headless mode. Supported cross-platform by Chromium, Chrome, Edge, Brave and Firefox.
• Function callback(err, instance)

instance

Browser instance object.

Properties:

• Object process - reference to instance's process started with Node's child_process.spawn API
• Number pid - instance's process PID
• Stream stdout - instance's process STDOUT stream
• Stream stderr - instance's process STDERR stream

Events:

• stop - fired when instance stops

Methods:

• unref()
• stop(callback) - stop the instance and fire the callback once stopped

Known Issues

• 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)
• Chrome @ OSX: it's not possible to launch multiple instances of Chrome at once

License

MIT