Cypress integration is currently only available in enterprise clouds.

This article walks you through setting up the Perfecto-Cypress integration. Cypress is a growing web front-end testing solution. Perfecto customers can utilize the Perfecto-Cypress SDK, which provides the following functionality:

  • Running Cypress tests in the cloud in parallel and at scale
  • Running Cypress tests from a cloud and a secured repository from the command-line of a continuous integration (CI) tool, such as Jenkins
  • Enhanced quality visibility, tagging, and debugging

Key benefits of Perfecto with Cypress include:

  • Fast and scalable execution in the cloud: more OS versions, parallel test execution, and same-day support for new browser versions
  • Full integration with CI/CD: executable from CI and the command line
  • Seamless installation and full compliance with Cypress open-source
  • Secure execution in the cloud
  • Advanced reporting and analysis
  • Unified solution for Selenium, WebDriverIO, and other frameworks as well as Cypress testing

Support info

Perfecto’s Cypress SDK is fully compliant with the Cypress technology. It supports the following operating systems and browsers:

  • Windows: Google Chrome, Mozilla Firefox, Microsoft Edge
  • Mac: Google Chrome, Mozilla Firefox

In addition, Perfecto supports Cypress projects with access to private libraries using the .npmrc file of the NPM package manager. This feature requires the latest version of the Perfecto-Cypress SDK.

Cypress versions 5.6.0,, and 8.1.0 are cached. All other versions are supported. For performance reasons, we recommend that you specify one of the cached Cypress versions in your configuration. Otherwise, the execution takes an additional 4 minutes.

For more information, see Supported platforms > Test frameworks > Cypress.


The integration requires that the following be installed:

  • NodeJS


    Make sure that you choose a NodeJS version supported by your requested Cypress version. For more information, see the Cypress Changelog.

  • The IDE of your choice

Network prerequisites

If you connect via VPN, for smooth Cypress execution, make sure the following URLs are accessible from your network:

  • <your-cloud>

  • <your-cloud>

  • Access to the npm registry or any other custom registry you use

If these URLs are not accessible, Cypress execution may be limited in that executions will run, but Cypress will not run and no tests will be executed or shown in the SDK.

Project prerequisites

When working with Perfecto Connect, the uploaded project, including any 3rd-party package used, should be able to work behind a proxy without any issue.

An example of a problematic 3rd-party package would be one that makes use of axios, which currently has a problem working behind a proxy. Therefore, projects using such a package cannot work with Perfecto Connect.

SDK proxy configuration

If you need to work behind a proxy when using the Perfecto-Cypress SDK, configure the following environment variable on your workstation: https_proxy


The variable name is case sensitive. Make sure to use only lowercase characters.

Step-by-step instructions

This section provides detailed setup instructions. To summarize: You install Cypress, the Perfecto-Cypress SDK, and the SDK configuration files in the same folder and in this exact order. The installation folder is a new folder that you create inside your IDE's Cypress workspace folder. This folder is also referred to as the Cypress test folder.

Perfecto-config.json details

Option Example Description Required
"cloud": "scouter",
"securityToken": "***"
Specifies the credentials used to initiate the communication with Perfecto services.

Can also be provided as a CLI parameter.

    "deviceType": "Web",
"platformName": "Windows",
"platformVersion": "10",
"browserName": "Chrome",
"browserVersion": "80",
"resolution": "1024x768",
"location": "US East",
"maxNumOfDevices": 2

Specifies the required capabilities.


Parallel execution

The maxNumOfDevices capability controls the number of allocated machines while running Cypress. Adjusting this number can improve execution performance because the specs are distributed equally among the allocated machines. This minimizes the overall execution time.

If maxNumOfDevices is not provided, Cypress execution minimizes the session execution time by allocating as many machines as possible to the session while taking into consideration the number of available licenses.

Note that not specifying this capability can affect the number of available licenses, thus limiting other web executions, such as Selenium. Therefore, as a best practice, we recommend starting with a value of "maxNumOfDevices": 1 and increasing it as needed.

For more information about available capabilities, see Define capabilities.

For each configuration, you also need to add the Perfecto Connect tunnelId value. For example:

      "deviceType": "Web",
      "platformName": "Windows",
      "platformVersion": "10",
      "browserName": "Chrome",
      "browserVersion": "latest",
      "resolution": "1024x768",
      "location": "US East",
      "tunnelId": "6d82110a-7cbe-4916-8428-ab4260d29382" 

For more information, see Associate a device with a Perfecto Connect tunnel.


Specifies the path to the tests folder. This folder should include the following:

  • Cypress test files
  • Configuration files (cypress.json, and package.json).

This is also the folder that the SDK packs and uploads to the Perfecto cloud.

perfecto-config.json can be located anywhere in the project or even reside outside of the project, but you need to make sure that tests.path provides a valid path to the folder where the Cypress test files reside, along with cypress.json and package.json.

Can be provided also as a CLI parameter.
Specifies a list of patterns to exclude from the tests' zip archive. Optional
Specifies a pattern to guide the SDK which test specs to run. Can be provided also as a CLI parameter

Specifies the major Node.js version for the Cypress execution environment.

Supported values:

["10" "12" "14"]

We will use the latest release for the selected major version.


NodeJS 14 is not supported with Windows 7. This is a NodeJS limitation.


"CYPRESS_BASE_URL": "https//"

Specifies the environment variables that your Cypress tests need. 

"job": {
"name": "some_job",
"number": 1,
"branch": "some_branch"
"project": {
"name": "My_Cypress_project",
"version": "v1.0"
"customFields": [
"name": "field-name",
"value": "field-name"
"author": "",
"tags": [
Specifies information for Perfecto Smart Reporting. For more information, see Smart Reporting capabilities. Optional
"My Cypress project"
The name used as the Report Name for the Report Library and Live Stream interfaces. See also Smart Reporting capabilities. optional

Best practices

This section lists best practices, recommendations, and clarifications that will help you avoid common pitfalls.

  • supportFile: This option is part of the cypress.json file. Make sure it is set to true for Cypress reports to be included in Perfecto Smart Reporting. If you remove it from the file, it is enabled by default. However, if you set it to false, the Cypress tests will not appear in Perfecto Smart Reporting.

  • Project hierarchy: Use the sample project as a template. You can clone it and start from there.

    A few words on the most important locations and relationships:

    • Tests are usually located in the Cypress/Integration folder.

    • The cypress.json and package.json files need to be located in the project's root folder.

    • The perfecto-config.json file can be located anywhere in the project or even outside of the project, but the tests.path option must provide a valid path to the folder where the Cypress test files reside, along with cypress.json and package.json.

  • Latest version: Make sure to always work with the latest version of the perfecto-cypress-reporter and perfecto-cypress-sdk.