> For the complete documentation index, see [llms.txt](https://cypress.visual-image-diff.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cypress.visual-image-diff.dev/getting-started/cypress-integration/browserstack.md).

# Browserstack

## Setup

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:

    <pre class="language-json" data-full-width="true"><code class="lang-json">"downloads": ["./cypress-image-diff-screenshots", "./cypress-image-diff-html-report"]
    </code></pre>
* add all your test running dependencies to `npm_dependencies`

Recommended changes

* update the browsers section according to your preferences
  * *reference:* [*https://www.browserstack.com/docs/automate/cypress/browsers-and-os*](https://www.browserstack.com/docs/automate/cypress/browsers-and-os)

## Running the tests

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

*Reference:* [*https://www.browserstack.com/docs/automate/cypress#run-your-first-test*](https://www.browserstack.com/docs/automate/cypress#run-your-first-test)

## Artifacts

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.&#x20;

*Reference:* [*https://www.browserstack.com/docs/automate/cypress/custom-reports-build-artifacts*](https://www.browserstack.com/docs/automate/cypress/custom-reports-build-artifacts)

## 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:

```typescript
describe('template spec', () => {
  it('passes', () => {
    cy.visit('../../report-example.html')
    cy.contains('Data Hub home page search bar - chrome').should('be.visible')
    cy.compareSnapshot(`${Cypress.env('BROWSER')}-example`)
  })
})
```

When running the&#x20;

`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 `browserstack.spec.cy.ts-chrome@latest:OS X Ventura-example.png`

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

## Example project setups

#### Javascript

<https://github.com/tamasmagyar/cypress-image-diff-js-browserstack-integration>

#### Typescript

<https://github.com/tamasmagyar/cypress-image-diff-js-browserstack-integration-typescript>

## Example browserstack.json

```json
{
    "auth": {
        "username": "your_username",
        "access_key": "your_access_key"
    },
    "browsers": [
        {
            "browser": "chrome",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        }
    ],
    "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
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cypress.visual-image-diff.dev/getting-started/cypress-integration/browserstack.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.