Restriction: Cypress integration is currently only available in enterprise clouds. Enablement requires a support ticket. If you are an enterprise cloud user interested in this integration, contact Perfecto Support.

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
Restriction: Mac runs are limited to the number of Mac machines available in a particular cloud . You can add the maxNumOfDevices capability to prevent more Mac machines from being requested than are available, a situation that would result in an error and blocked tests.

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

To learn even more about Cypress, consider taking our BlazeMeter University course. Guided by Cypress guru Gleb Bahmutov, you will learn how to use Cypress 10 to do end-to-end testing for your web apps.

Important: This document includes references to a third-party product, Cypress. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Cypress, see

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 10.11.0, 11.2.0, 12.17.2, and 13.1.0 are cached. All other versions are supported. For performance reasons, consider specifying one of the cached Cypress versions in your configuration. Otherwise, the execution takes an additional 4 minutes.

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

If you want to start working with Cypress 10, see Migrate to Cypress version 10 or later.


The integration requires that the following be installed:

  • NodeJS

    Important: 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, you need to configure the following environment variable on your workstation: HTTPS_PROXY

Important: The variable name is case sensitive. Make sure to use only uppercase characters.

For a proxy without authentications, set the following:

HTTPS_PROXY=http://<proxy ip>:<proxy port>

For proxy with authentications, set the following:

HTTPS_PROXY=http://<username>:<password>@<proxy ip>:<proxy port>

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.

If you need to run scripts on a virtual machine (VM) before and after running a Cypress test, see Run scripts on a VM before or after a test.

Perfecto-config.json details




"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.

For more information about available capabilities, see Define capabilities.

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

      "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.

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, consider starting with a value of "maxNumOfDevices": 1 and increasing it as needed.

maxNumOfDevices is especially useful when targeting MacOS because the amount of Mac machines available on a cloud is limited. You need to make sure that the system is not trying to allocate more machines than are available.


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.


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:

["14" "16" "18"]

For comprehensive support information, see Supported platforms.




"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.


"My Cypress project"

The name used as the Report Name for the Report Library and Live Stream interfaces. See also Smart Reporting capabilities.


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 perfecto-cypress-reporter and perfecto-cypress-sdk.