This post walks through configuring your existing Cypress tests to execute in parallel on Browserstack remote browsers.

Browserstack is not the go-to service for making your Cypress tests run in parallel as it's a premium level cross browser testing tool. If you are just looking for a way to run your Cypress tests in parallel you may want to consider a free Cypress plugin called cypress-split.

Though if your company already has a licence for Browserstack which you have access to then see the solution below.

TL;DR

See this repo for an example solution using the Browserstack CLI to run tests in parallel on their remote browsers.

For these steps I will be referencing this example Cypress repo which runs tests from 3 files.

Browserstack Account

If you don't have an account yet head to browserstack.com. You can create a free trial account.

Browserstack CLI

Install the Browserstack Cypress CLI globally.

npm install -g browserstack-cypress-cli

This CLI runs tests by compressing your Cypress project then uploading to the Browserstack remote VMs. The dependencies required are installed there. Keep in mind this can delay the tests from getting started, so slightly reducing any time gained from a parallel run.

Now in the root directory of your existing Cypress framework run browserstack-cypress init. This will create a settings file called browserstack.json

Amend the file by adding your username and access key or better still set these values as environment variables BROWSERSTACK_USERNAME & BROWSERSTACK_ACCESS_KEY then remove these fields from the file.

Example file used for my project. I removed all the browsers except Chrome on Windows 10 as I do not need cross browser testing. If you have more browsers each thest will repeat for each browser/OS set.

{
  "browsers": [
    {
      "browser": "chrome",
      "os": "Windows 10",
      "versions": ["latest"]
    }
  ],
  "run_settings": {
    "cypress_config_file": "cypress.config.js",
    "project_name": "cypress browserstack example",
    "build_name": "repo build",
    "exclude": [],
    "parallels": "3",
    "npm_dependencies": {},
    "package_config_options": {},
    "headless": true
  },
  "connection_settings": {
    "local": false,
    "local_identifier": null,
    "local_mode": null,
    "local_config_file": null
  },
  "disable_usage_reporting": false
}

Set your NPM Script

Set an NPM script to call the Browserstack cli run command.

  "scripts": {
    "test:browserstack": "browserstack-cypress run"
  }

Note you can pass in switch --config which can have any of the normal Cypress config such as --config baseurl="https://testingnotebook.com" or browser=chrome etc. See here for more information.

Run your Tests

Call the NPM script you set npm run test:browserstack.

...
All tests:

----------------------------------------------------------------------------------------------------------------------------------------------------------------
 Chrome 117 (Windows 10)           :   cypress/e2e/homepage.cy.js ✔ [passed]
 Chrome 117 (Windows 10)           :   cypress/e2e/post.cy.js ✔ [passed]
 Chrome 117 (Windows 10)           :   cypress/e2e/about.cy.js ✔ [passed]
----------------------------------------------------------------------------------------------------------------------------------------------------------------

Failed / skipped test report:
+--------------------------------------------------------------+--------+---------+-------------------------+
| Spec                                                         | Status | Browser | BrowserStack Session ID |
+--------------------------------------------------------------+--------+---------+-------------------------+

Total tests: 3, passed: 3, failed: 0, skipped: 0, passed_with_skipped: 0, pending: 0
Done in 92 seconds using 3 machines
...

The output shows the tests ran on Browserstack with no issue.

Optional Steps

Dependencies

If your Cypress framework has any dependencies used in your tests, such as testing-library, you will need to include these in the dependencies object within the browserstack.json file so they can be installed on their remote VMs.

Local Tunnel

If you're running the tests against a private test environment you will need to set the local value to true in the browserstack.json file.

Exclude Unneeded Directories

To optimise the test build use the exclude object to exclude any files or directories not needed to be uploaded to the Browserstack virtual VMs.

Git Ignore

You may need to incude these in your .gitignore file.

runner-results/
log/
npm_install_debug.log
results/
tmpBstackPackages/

For more information on Cypress Browserstack integration see the official documentationreadme.

The code used for this post can be found here.