Install browserstack-cypress-cli package

  • yarn add browserstack-cypress-cli OR npm i browserstack-cypress-cli

Run browserstack-cypress-cli init

  • This will generate your browserstack.json file

Update the generated browserstack.json file with your Browserstack credentials and some configs

Required changes

  • replace the auth credentials

  • update cypress_config_file location, e.g. to cypress.config.js

  • update parallels option, e.g. to "1"

  • set downloads to your cypress-image-diff screenshot and report location:

    • it will be used later on when updating baseline images

    • for example:

      "downloads": ["./cypress-image-diff-screenshots", "./cypress-image-diff-html-report"]
  • add all your test running dependencies to npm_dependencies

Recommended changes

Running the tests

You can now run the tests with the browserstack-cypress run command



Upon running the browserstack-cypress run command with the --sync flag. It will sync the Browserstack build's artifacts to your local machine under build_artifacts folder.


Updating baseline images

After running the tests with the previously mentioned browserstack-cypress run command you can simply copy the given comparison image from your local build_arfifacts/build_id/../../cypress-image-diff-screenshots/comparison folder and move it to the cypress-image-diff-screenshots/baseline images folder. Which will serve as the new basline images for any futures test runs.

Creating browser + OS specific baseline images

In order to create browser specific baseline image we can use Cypress environmental variables.

For example:

describe('template spec', () => {
  it('passes', () => {
    cy.contains('Data Hub home page search bar - chrome').should('be.visible')

When running the

CYPRESS_BROWSER="chrome@latest:OS X Ventura" browserstack-cypress run --sync --browser "chrome@latest:OS X Ventura"

  • It will override the browser configs in browserstack.json file

  • Tests will generate browser/OS specific baselines image like X Ventura-example.png

Drawback: You have to trigger a new browserstack build for each browser and OS combinations

Example project setups



Example browserstack.json

    "auth": {
        "username": "your_username",
        "access_key": "your_access_key"
    "browsers": [
            "browser": "chrome",
            "os": "Windows 10",
            "versions": [
    "run_settings": {
        "cypress_config_file": "cypress.config.js",
        "project_name": "project-name",
        "build_name": "build-name",
        "exclude": [],
        "parallels": "1",
        "npm_dependencies": {
            "browserstack-cypress-cli": "^1.25.3",
            "cypress": "^13.2.0",
            "cypress-image-diff-js": "^1.30.1"
        "package_config_options": {},
        "headless": true
    "connection_settings": {
        "local": false,
        "local_identifier": null,
        "local_mode": null,
        "local_config_file": null
    "disable_usage_reporting": false

Last updated