Skip to main content
Transform your testing process with: Real Device Features, Company-wide Licences, & Test Observability

Specify Browsers and OS

Learn about setting the OS and browser combinations to run your Cypress tests.

Using BrowserStack, you can run your tests on multiple OS-browser combinations simultaneously. Set the combinations using either of the below options.

Setting the browser & OS keys in browserstack.json

Add the browsers object in the browserstack.json file to set a list of OS, browsers, and browser versions that you want to use.

The sample structure of the browsers object is as follows:

browserstack.json
{
  ...
  "browsers": [{
      "os": "<Name of the OS>",
      "browser": "<Name of the browser>",
      "versions": ["latest", "latest-1", "latest-2"],
    }
  ]
  ...
}

The following table explains the different keys under the browsers object.

key value Possible values
os Name of the operating system Windows 10, Windows 11, OS X Mojave, OS X Catalina, OS X Big Sur, OS X Monterey and OS X Ventura
browser Name of the browser webkit, chrome, firefox and edge
versions A list of supported browser versions WebKit: 16 and above,
Chrome: 66 and above (except 82)
Firefox: 70 and above
Edge: 80 and above (except 82)

It is recommended that you use latest, latest-1, latest-2, and so on, to test on the latest n versions of the required browser.
Note: Check out the list of all BrowserStack supported browsers and operating systems for Cypress.

Consider the following snippet that shows a sample configuration if you want to run the following OS-browser combination. It is recommended that the latest, latest-1, latest-2, etc. values are used for always using the latest browser versions.

  • Chrome on Windows 10
  • Edge on Windows 10
  • WebKit on OS X Big Sur
  • Firefox on any OS (run your test on any OS combination to ensure stability and performance)
browserstack.json
{
  ...
  "browsers": [{
      "os": "Windows 10",
      "browser": "chrome",
      "versions": ["latest", "latest-1", "latest-2"],
    },
    {
      "os": "Windows 10",
      "browser": "edge",
      "versions": ["latest", "latest-1", "latest-2"],
    },
    {
      "os": "OS X Big Sur",
      "browser": "webkit",
      "versions": ["latest", "latest-1", "latest-2"],
    },
    {
      "browser": "firefox",
      "versions": ["latest", "latest-1", "latest-2"],
    }
  ]
  ...
}
Protip: If running on a specific Operating System is not your use-case, you can choose to omit os from the browserstack.json. We would run your tests on the best possible OS combination keeping stability and performance in mind.

Using WebKit (Experimental)

Cypress has experimental support for WebKit, Safari’s browser engine. To run Cypress tests on WebKit, ensure that the experimentalWebKitSupport capability is set to true in your Cypress config file.

  1. Set the following configuration in your cypress.config.js file:

    cypress.config.js
     const { defineConfig } = require('cypress')
     module.exports = defineConfig({
       experimentalWebKitSupport: true
       // the rest of the config settings
       },
     )
    
  2. Set the following configuration in your browserstack.json file:

    browserstack.json
     {
       ...
       "browsers": [
         {
           "os": "OS X Big Sur",
           "browser": "webkit",
           "versions": ["latest"],
         }
       ]
       ...
     }
    
Note: Ensure you specify the correct Webkit version for the respective os. Check out the supported Webkit versions for various os.

Using the CLI

For CLI versions v1.11.0 or higher, you can also pass the browser and OS combinations through the CLI command. The sample command for the following OS-browser combinations is as follows:

Command Line
browserstack-cypress run --browser "<browser_name>@<browser_version>:<OS_version>","<browser_name>@<browser_version>:<OS_version>"
Argument Accepted values
--browser Accepts a comma-separated list of browser, browser version, and OS combinations. Build runs only on the list of specified browsers.

For example, --browser "chrome@latest:Windows 10","webkit@latest:OS X Big Sur","firefox@latest-1:OS X Catalina".
Note: The --browser option is only supported for browserstack-cypress-cli version v1.11.0 and higher. The values that you pass using the CLI command overrides the settings in the browserstack.json file.

Consider the following snippet that shows a sample CLI command if you want to run the following OS-browser combination. It is recommended that the latest, latest-1, latest-2, etc. values are used for always using the latest browser versions.

  • Chrome on Windows 10
  • Firefox on OS X Catalina
Command Line
browserstack-cypress run --browser "chrome@latest:Windows 10","webkit@latest:Big Sur","firefox@latest-1:OS X Catalina"
Warning: Your Cypress tests will fail in Firefox v105 and later. Specify Firefox v104 or earlier for your Cypress tests to run successfully.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Download Copy