@xerox/browserslist-browserstack v2.1.4

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. 1. Install the npm module:

yarn add @xerox/browserslist-browserstack --dev
# or
npm install @xerox/browserslist-browserstack --save-dev

2. 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';

3. 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.

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