Integrate your Cypress tests with Percy

Create a Percy project
Sign in to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it set your environment variable in the next step.

For details on creating a project, see Create a Percy project.

Set the project token as an environment variable
Run the given command to set PERCY_TOKEN as an environment variable:

To learn about environment variables in Percy, see Percy environment variables.

Install Percy dependencies
Install the components required to establish the integration environment for your test suite.

To install the dependencies, run the following command:

Update your test script

Import the Percy library to use the method and attributes required to take screenshots.

In order to add Percy snapshots to your Cypress tests, you have to first import the @percy/cypress package into your cypress/support/e2e.js file:

This gives you access to the Percy snapshot command in any of your Cypress tests, via cy.percySnapshot(). You can now incorporate visual tests in your existing suite:

The snapshot method arguments are:

• name - The snapshot name; must be unique to each snapshot; defaults to the test title
• options - See per-snapshot configuration options

For example:

To learn more, see Percy snapshot.

Run Percy
Run your tests using the percy exec command as shown below:

Create a Percy project

Sign in to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it to set your environment variable in the next step.

For details on creating a project, see Create a Percy project.

Set the project token as an environment variable

Run the given command to set PERCY_TOKEN as an environment variable:

To learn about environment variables in Percy, see Percy environment variables.

Install Percy and BrowserStack Cypress CLI dependencies

Install the components required to establish the integration environment for your test suite.

To install the dependencies, run the following command:

# Install the BrowserStack Cypress CLI
npm install -g browserstack-cypress-cli
# Install the Percy and Cypress CLI
npm install --save-dev @percy/cypress

Create the configuration file

Create and configure the browserstack.json file which contains configurations, such as BrowserStack credentials, capabilities, etc., that are required for running the tests. Use the following init command to initialize the app project folder and create a boilerplate browserstack.json file:

browserstack-cypress init

After the browserstack.json file is created, modify or add the mandatory configurations that are required to run the Cypress test as shown in the following sample code. The mandatory configurations are BrowserStack credentials, Turboscale parameters, Cypress configuration file, browser-device combinations, and the number of parallels:

// browserstack.json

{
  "auth": {
    "username": "YOUR_USERNAME",
    "access_key": "YOUR_ACCESS_KEY"
  },
  "browsers": [{
      "browser": "chrome",
            "os": "linux",
            "versions": "latest"
    } 
  ],
  "run_settings": {
        "cypress_config_file": "./cypress.config.js",
        "project_name": "new-project",
        "build_name": "new-build",
        "exclude": [],
        "parallels": "2",
        "npm_dependencies": {
            "react": "^18.2.0",
            "react-dom": "^18.2.0",
            "react-modal": "^3.16.1",
            "react-router-dom": "^6.15.0",
            "@percy/cypress": "^3.1.6",
            "system_env_vars": ["PERCY_TOKEN"]
        },
        "record": true,
        "record-key": "87b774c4-a373-43fa-986e-0833a55dc6d7",
        "projectId": "2m6i88",
        "package_config_options": {},
        "headless": true,
        "turboScale": true,
        "turboScaleOptions": {
            "gridName": "turboscale-trial-grid"
        }
    },
    "disable_usage_reporting": true
}

In the above sample code snippet, the following parameters are mandatory to run the test:

• username, access_key
• browser, os
• projectId, turboScale
• PERCY_TOKEN

For more information, see Run your first Cypress test with Automate Turboscale.

Update your test script

Import the Percy library to use the method and attributes required to take screenshots.

In order to add Percy snapshots to your Cypress tests, you have to first import the @percy/cypress package into your cypress/support/e2e.js file:

This gives you access to the Percy snapshot command in any of your Cypress tests, via cy.percySnapshot(). You can now incorporate visual tests in your existing suite:

The snapshot method arguments are:

• name - The snapshot name; must be unique to each snapshot; defaults to the test title
• options - See per-snapshot configuration options

For example:

Run tests

Run the test using the following command:

npx browserstack-cypress run