browserslist-browserstack

Run BrowserStack tests for all browsers in project’s Browserslist config (with additional include/exclude filters).

Setup

Important Note: In order to use this package a BrowserStack account with a valid Automate plan is required, a free trial is available.

browserslist-browserstack is an npm module, so getting things up and running is simple.

Install the npm module:

yarn add browserslist-browserstack --dev
# or
npm install browserslist-browserstack --save-dev

Import it into a project (e.g. browserstack.test.js or whatever convention your testing suite uses):

const getCapabilities = require('browserslist-browserstack').default;
// or
import getCapabilities from 'browserslist-browserstack';

Pass options to customize the list of capabilites. See options for more details:

import { BrowserFilter, OperatingSystemFilter }, getCapabilities from 'browserslist-browserstack';

const capabilities = await getCapabilities({
  username: 'browserstack-username',
  accessKey: 'browserstack-accesskey',
  browsers: {
    include: [
      BrowserFilter.Firefox
    ]
  },
  operatingSystems: {
    exclude: [
      OperatingSystemFilter.OSX
    ]
  }
});

Example

The main use case for using browserslist-browserstack is to test websites across a number of different browsers and operating systems, without having to manually specify them or update them everytime a new browser version is released. The example below shows a minimal use-case using selenium-webdriver to run integration tests for https://www.google.com on BrowserStack's Automate platform. This code would likely be included as part of a testing suite like Jest or Mocha, and perform some relevant assertions like detecting JS errors on a webpage for different browsers. View the source code

Running the above code, providing valid BROWSER_STACK_KEY and BROWSER_STACK_KEY environment variable are set, would result in the following 3 tests being run on BrowserStack (browser versions will change as new ones are released, but should always be the latest):

Options

Note: none of these options are required, by default getCapabilities will just return the list straight from BrowserStack's REST API provided BROWSER_STACK_USERNAME and BROWSER_STACK_ACCESS_KEY are set, and are valid.

Option	Type	Description	Example	Default
username	`String`	A BrowserStack Username to use when requesting supported capabilities for an account.	`"username"`	`process.env.BROWSER_STACK_USERNAME`
accessKey	`String`	A BrowserStack Access Key to use when requesting supported capabilities for an account.	`"xxxxxxxxxxxxxxxxxxxx"`	`process.env.BROWSER_STACK_ACCESS_KEY`
browserslist	`Object`	Options to pass to Browserslist. See Browserslist options.	`{ queries: ['> 1%', 'IE 10'], options: { ignoreUnknownVersions: true } }`	`undefined`
browsers.include	`Array`	A list of BrowserFilter's to include in the capabilities list.	`[BrowserFilter.FIREFOX, BrowserFilter.CHROME]`	`[]`
browsers.exclude	`Array`	A list of BrowserFilter's to exclude in the capabilities list.	`[BrowserFilter.IE, BrowserFilter.EDGE]`	`[]`
operatingSystems.include	`Array`	A list of OperatingSystemFilter's to include in the capabilities list.	`[OperatingSystemFilter.WINDOWS]`	`[]`
operatingSystems.exclude	`Array`	A list of OperatingSystemFilter's to exclude in the capabilities list.	`[OperatingSystemFilter.OSX]`	`[]`
operatingSystemVersion.include	`Array`	A list of operatingSystemVersion's to include in the capabilities list.	`[operatingSystemVersion.SEVEN, operatingSystemVersion.XP]`	`[]`
operatingSystemVersion.exclude	`Array`	A list of operatingSystemVersion's to exclude in the capabilities list.	`[operatingSystemVersion.EL_CAPITAN, operatingSystemVersion.HIGH_SIERRA]`	`[]`
formatForSelenium	`Boolean`	Whether to add browserName and browserVersion properties to the outputted capabilites, as selenium does not understand BrowserStack's `browser` and `browser_version` equivelants.	`false`	`true`

Types

These are the core types exported by browserslist-browserstack.

BrowserFilter

An enum of browsers to filter capabilites, possible values:

FIREFOX
SAFARI
IE
CHROME
OPERA
EDGE

OperatingSystemFilter

An enum of operating systems to filter capabilites, possible values:

WINDOWS
OSX

WindowsOperatingSystemVersionFilter

An enum of windows versions to filter capabilities, possible values:

XP
SEVEN
EIGHT
EIGHT_ONE
TEN

OSXOperatingSystemVersionFilter

An enum of macOS versions to filter capabilities, possible values:

SNOW_LEOPARD
LION
MOUNTAIN_LION
MAVERICKS
YOSEMITE
EL_CAPITAN
SIERRA
HIGH_SIERRA
MOJAVE

Options

An interface to define the possible options to pass to getCapabilities. See options.

ResponseError

A custom error class which indicates errors caused if a node-fetch response is not in the range [200,300]. Mainly used to catch 401 Unauthorized errors when trying to pull capabilities from BrowserStack's REST API.

FetchError

For convinience, just fowards the class from node-fetch.

BrowsersListError

For convinience, just fowards the class from Browserslist.

Error Handling

If a request to BrowserStack's REST API encounters an issue one of these errors will be thrown:

ResponseError
FetchError
AbortError

If there is an issue parsing queries with Browserslist a BrowsersListError will be thrown.

See node-fetch docs and Browserslist docs for more details.

Useful links

BrowserStack Automate: required service to run tests on remote machines with a webdriver.
Browserslist: used to query browser versions.
selenium-webdriver: allows control of remote browsers on BrowserStack's Automate platform.
browserstack-local: allows testing of local pages that aren not hosted on a web server.

LICENSE | CHANGELOG | ISSUES

npm