browserstack

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 browserslist-browserstack --dev
# or
npm install 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.

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
• YANDEX

OperatingSystemFilter

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

• WINDOWS
• OSX
• IOS
• ANDROID

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
• CATALINA
• BIG_SUR
• MONTEREY
• VENTURA

iOSOperatingSystemVersionFilter

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

• TEN
• ELEVEN
• TWELVE
• THIRTEEN
• FOURTEEN
• FIFTEEN
• SIXTEEN
• SIXTEEN_THREE
• SIXTEEN_FOUR
• SIXTEEN_FIVE

AndroidOperatingSystemVersionFilter

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

• FOUR_FOUR
• FIVE
• FIVE_ONE
• SIX
• SEVEN
• SEVEN_ONE
• EIGHT
• EIGHT_ONE
• NINE
• TEN
• ELEVEN
• TWELVE
• THIRTEEN

DeviceFilter

• GALAXY_A10
• GALAXY_A11
• GALAXY_A51
• GALAXY_A52
• GALAXY_A8
• GALAXY_J7_PRIME
• GALAXY_M32
• GALAXY_M52
• GALAXY_NOTE_10
• GALAXY_NOTE_10_PLUS
• GALAXY_NOTE_20
• GALAXY_NOTE_20_ULTRA
• GALAXY_NOTE_8
• GALAXY_S10
• GALAXY_S10_PLUS
• GALAXY_S10E
• GALAXY_S20
• GALAXY_S20_PLUS
• GALAXY_S20_ULTRA
• GALAXY_S21
• GALAXY_S21_PLUS
• GALAXY_S21_ULTRA
• GALAXY_S22
• GALAXY_S22_PLUS
• GALAXY_S22_ULTRA
• GALAXY_S23
• GALAXY_S23_ULTRA
• GALAXY_S8
• GALAXY_S9
• GALAXY_S9_PLUS
• GALAXY_TAB_S5E
• GALAXY_TAB_S6
• GALAXY_TAB_S7
• GALAXY_TAB_S8
• HUAWEI_P30
• IPAD_10TH
• IPAD_5TH
• IPAD_6TH
• IPAD_7TH
• IPAD_8TH
• IPAD_9TH
• IPAD_AIR_2
• IPAD_AIR_2019
• IPAD_AIR_4
• IPAD_AIR_5
• IPAD_MINI_2019
• IPAD_MINI_2021
• IPAD_MINI_3
• IPAD_MINI_4
• IPAD_PRO_11_2018
• IPAD_PRO_11_2020
• IPAD_PRO_11_2021
• IPAD_PRO_11_2022
• IPAD_PRO_12_9
• IPAD_PRO_12_9_2018
• IPAD_PRO_12_9_2020
• IPAD_PRO_12_9_2021
• IPAD_PRO_12_9_2022
• IPAD_PRO_9_7_2016
• IPHONE_11
• IPHONE_11_PRO
• IPHONE_11_PRO_MAX
• IPHONE_12
• IPHONE_12_MINI
• IPHONE_12_PRO
• IPHONE_12_PRO_MAX
• IPHONE_13
• IPHONE_13_MINI
• IPHONE_13_PRO
• IPHONE_13_PRO_MAX
• IPHONE_14
• IPHONE_14_PLUS
• IPHONE_14_PRO
• IPHONE_14_PRO_MAX
• IPHONE_6
• IPHONE_6_PLUS
• IPHONE_6S
• IPHONE_6S_PLUS
• IPHONE_7
• IPHONE_8
• IPHONE_8_PLUS
• IPHONE_SE
• IPHONE_SE_2020
• IPHONE_X
• IPHONE_XR
• IPHONE_XS
• IPHONE_XS_MAX
• MOTO_G7_PLAY
• MOTO_G71_5G
• MOTO_G9_PLAY
• ONEPLUS_11R
• ONEPLUS_6T
• ONEPLUS_7
• ONEPLUS_7T
• ONEPLUS_8
• ONEPLUS_9
• OPPO_A78
• OPPO_A96
• OPPO_RENO_3_PRO
• OPPO_RENO_6
• PIXEL_2
• PIXEL_3_XL
• PIXEL_3A
• PIXEL_3A_XL
• PIXEL_4
• PIXEL_4_XL
• PIXEL_5
• PIXEL_6
• PIXEL_6_PRO
• PIXEL_7
• PIXEL_7_PRO
• REALME_8
• REDMI_NOTE_11
• REDMI_NOTE_12_PRO
• REDMI_NOTE_8
• REDMI_NOTE_9
• VIVO_V21
• VIVO_Y15
• VIVO_Y21
• VIVO_Y22
• VIVO_Y50

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