Capabilities

Using Cypress with BrowserStack requires setting up the browserstack.json file with custom capabilities. This section includes a sample browserstack.json file along with a detailed reference of all the supported capabilities.

Cypress v10 and higher
Cypress v9 and lower

  browserstack.json
{
    "auth": {
        "username": "YOUR_USERNAME",
        "access_key": "YOUR_ACCESS_KEY"
    },
    "browsers": [
        {
            "browser": "chrome",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        },
        {
            "browser": "firefox",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        },
        {
            "browser": "edge",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        }
    ],
    "run_settings": {
        "nodeVersion": "<auto populated node version>",
        "cypress_version": "12.3",
        "cypress_config_file": ".<path/to/your/cypress.config.js/file>",
        "home_directory": "</path/to/your/projects/root_directory/name_of_root_directory>",
        "specs": ["cypress/e2e/1-getting-started/todo.cy.js", "cypress/e2e/2-advanced-examples/actions.cy.js"],
        "spec_timeout": 10,
        "npm_dependencies": {
            "npm-package-you-need-to-run-tests-1": "^1.2.1",
            },
        "package_config_options": {
            "npm-package-you-need-to-run-tests-1_options": {
                "option1": true,
                "option2": "some-value"
            }},
        "exclude": ["some-folder/test.cy.js", "static/*.pdf"],
        "system_env_vars": ["NPM_TOKEN", "GITHUB_SECRET", "<ANY_OTHER_ENV_VAR_AVAILABLE_IN_YOUR_SYSTEM>"],
        "project_name": "My sandbox project",
        "build_name": "Build no. 1",
        "build_tag": "reg",
        "parallels": "5",
        "record": true,
        "record-key": "<your_record-key>",
        "projectId": "<your_cypress_project_id>",
        "geolocation": "<country_code>",
        "debug": true,
        "headless": true
    },
    "connection_settings": {
        "local": true,
        "local_identifier": "local_connection_name",
        "local_mode": "always-on",
        "local_config_file": "/path/to/your/config.yml"
    },
    "disable_usage_reporting": false
}

  browserstack.json
{
    "auth": {
        "username": "YOUR_USERNAME",
        "access_key": "YOUR_ACCESS_KEY"
    },
    "browsers": [
        {
            "browser": "chrome",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        },
        {
            "browser": "firefox",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        },
        {
            "browser": "edge",
            "os": "Windows 10",
            "versions": [
                "latest",
                "latest-1"
            ]
        }
    ],
    "run_settings": {
        "nodeVersion": "<auto populated node version>",
        "cypress_version": "9.latest",
        "cypress_config_file": ".<path/to/your/cypress.json/file>",
        "home_directory": "</path/to/your/projects/root_directory/name_of_root_directory>",
        "specs": ["cypress/integration/1-getting-started/todo.cy.js", "cypress/integration/2-advanced-examples/actions.cy.js"],
        "spec_timeout": 10,
        "npm_dependencies": {
            "npm-package-you-need-to-run-tests-1": "^1.2.1",
            },
        "package_config_options": {
            "npm-package-you-need-to-run-tests-1_options": {
                "option1": true,
                "option2": "some-value"
            }},
        "exclude": ["some-folder/test.js", "static/*.pdf"],
        "system_env_vars": ["NPM_TOKEN", "GITHUB_SECRET", "<ANY_OTHER_ENV_VAR_AVAILABLE_IN_YOUR_SYSTEM>"],
        "project_name": "My sandbox project",
        "build_name": "Build no. 1",
        "build_tag": "reg",
        "parallels": "5",
        "record": true,
        "record-key": "<your_record-key>",
        "projectId": "<your_cypress_project_id>",
        "geolocation": "<country_code>",
        "debug": true,
        "headless": true
    },
    "connection_settings": {
        "local": true,
        "local_identifier": "local_connection_name",
        "local_mode": "always-on",
        "local_config_file": "/path/to/your/config.yml"
    },
    "disable_usage_reporting": false
}

The following table lists the supported Cypress capabilities and how they must be defined in the browserstack.json file:

Object	Key(Capabilities)	Value	Reference
`auth`	`username`	Your BrowserStack username which you can find in your account settings.	Set your username
`auth`	`access_key`	Your BrowserStack access key which you can find in your account settings.	Set your access key
`browsers`	`os` `browser` `versions`	Specify the OS where you want to run tests. Specify the browser where you want to run tests. Specify the browser version where you want to run tests.	Name of the operating system Name of the browser Version of the browser
`run_settings`	`nodeVersion`	Set the required node version to run your Cypress tests. Supported node versions are `14.19.1` and `16.15.0`	N/A
	`cypress_version`	`10.latest`, `9.Latest`, `8.Latest`, `7.Latest`, `6.Latest`	Set the required Cypress version
	`cypress_config_file`	Absolute or relative path to the Cypress configuration file. Set as `cypress.config.js` for v10 and above, and `cypress.json` for v9 and below.	Specify the Cypress configuration file that you want to use
	`home_directory`	Absolute or relative path to root directory in case of multiple `cypress.json` files.	Specify the root directory to avoid your test being failed
	`specs`	An array of patterns (file paths or regexes) that match the spec files that you want to run.	Specify the spec files that you want to run
	`spec_timeout`	Timeout value in case any spec with issues is killed and build continues.	Set the timeout duration for the spec files
	`npm_dependencies`	List of dependent `npm` packages that your project requires.	Set the npm dependencies required to run your Cypress tests
	`exclude`	An array of patterns (file paths or regexes) to exclude files that are not required.	Specify the files you want to exclude from your tests
	`system_env_vars`	Set and apply any system level environment variables to BrowserStack remote instances.	Define environment variables
	`project_name` `build_name` `build_tag`	String value to identify the project. String value to identify the build. String value to set a tag for your build.	Set your project name Set your build name Set a build tag
	`record` `record-key` `projectId`	Set `True` to generate test recording and publish to the Cypress dashboard. `record-key` generated for the project that can be found on the Cypress dashboard. `projectId` generated for the project that can be found on the Cypress dashboard.	Generate test results on the Cypress dashboard Record key from the Cypress dashboard Project ID from the Cypress dashboard
	`geolocation`	Country code for the location you want to simulate.	Simulate a specific geolocation
`connection_settings`	`local` `local_identifier` `local_mode` `local_config_file`	Test your locally hosted website on BrowserStack. Specify a unique Local Testing connection name. Specify the local mode. Specify additional configuration parameters.	Set up local testing
`debug`	na	Helps debug issues detected through your tests. Disabled by default. Set `True` to enable.
`disable_usage_reporting`	na	Set as `True` by default and is used by the CLI to collect anonymized usage data.	Enable or disable usage reporting

Did this page help you?

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!