Page tree
Skip to end of metadata
Go to start of metadata

Last updated: May 04, 2021 17:24

Only supported in private 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 quick 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

This solution is also compatible with TypeScript.

For additional resources, 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

Cypress versions 4.12.1, 5.6.0, 6.7.1., and 7.2.0 are cached. Cypress versions 3 and earlier are not supported.

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

On this page:


The integration require that the following be installed:

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.

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

Note: 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.  

1 | Install Cypress

  1. Launch a terminal in your IDE.
  2. In the workspace folder, create a new folder, for example CypressSEDemo (as shown in the images included in this article). This is the folder we refer to as tests root folder.
  3. Change to the new folder you created.
  4. Run the following command to create the package.json file:

    npm init
  5. To install Cypress, run the following command from the command line:

    npm install cypress --save-dev 

    --save-dev saves it as a dependency in the package.json file.

  6. To launch Cypress, run the following command: 

    npx cypress open

    This launches the Cypress UI and also creates a cypress folder inside the CypressSEDemo folder you created in step 1, including the cypress.json file. 

     Click to view image
  7. In the Cypress UI:
    1. Click any *.spec.js file and launch it in the selected browser.
    2. Close the Cypress UI.

2 | Install the Perfecto-Cypress SDK 

  1. Install the Perfecto-Cypress SDK by running the following command (make sure your location is inside the tests root folder, which includes the cypress folder):

    npm install perfecto-cypress-sdk --save-dev
  2. To add Perfecto Cypress Reporter capabilities, run the following command:

    npm install perfecto-cypress-reporter --save-dev 

3 | Initialize the Perfecto-Cypress SDK

To run Cypress tests in Perfecto, 3 configuration files are required in the tests root folder:

Note: Before running the init command, you need the path to the Cypress tests folder.

To initialize the SDK:

  1. Run the init command to generate perfecto-config.json (see also Perfecto config options):

    npx perfecto-cypress init --tests.path=./CypressSEDemo/ --skip

    where --skip omits the interactive questions that otherwise occur (about the cloud name, security token, etc.).

  2. In the perfecto-config.json file, define the following:
    • The cloud name, for example demo. The SDK automatically adds
    • The security token, either hard-coded or passed later as a parameter in the command line.
    • The test specs you want to execute in the cloud, for example **/*.specs.js for the specsExt parameter
  3. In the package.json file, specify one of the following Cypress versions. Otherwise, the execution takes an additional 4 minutes.

    • 4.12.1
    • 5.6.0
    • 6.8.0
    • 7.0.0
  4. Import perfecto-cypress-reporter into the support file cypress/support/index.js by adding the following code:

    import 'perfecto-cypress-reporter'; // or require('perfecto-cypress-reporter');
     Click to view image
  5. Use the following SDK commands as needed: run, pack, upload
    For more information on these commands, run the --help command.

    $ perfecto-cypress --help
    perfecto-cypress <command>
      perfecto-cypress init    init Perfecto and Cypress configuration files
      perfecto-cypress pack    Zip tests files according to configurations
      perfecto-cypress run     Run Cypress tests on Perfecto cloud
      perfecto-cypress upload  Upload tests zip archive to Perfecto cloud repository
      --version  Show version number                                       [boolean]
      --help     Show help                                                 [boolean]

    Alternative upload option

    As an alternative to the SDK, you can upload your project through the Perfecto UI. To do this, perform the following steps:

    1. Pack your project, as follows:

      1. Go to your project folder.

      2. Open a command line window.

      3. Run the following command to create a zip file of your project:

        npx perfecto-cypress pack
    2. Upload your compressed project to the Perfecto repository using the Perfecto UI (see also Manage the repository):

      1. In a browser, navigate to the URL of your Perfecto cloud.

      2. On the landing page, under Assets and Setup, click ACCOUNT SETUP.

      3. In the Repository view, click the upload icon  at the bottom right:

        1. Browse to the zip file you want to upload.

        2. In the File upload form, make sure that the name of the zip file is unique, select Private or Public, and click UPLOAD.

    3. From your project's root folder (where perfecto-config.json is located) , run your project with the tests.artifactKey parameter, as follows:

      npx perfecto-cypress run --tests.artifactKey=<PRIVATE/PUBLIC>:<zip file name>

4 | Execute Cypress test specs

For a quick execution, perform the following steps:

  1. Run the command from terminal, as follows:

    npx perfecto-cypress run --config=.\CypressSEDemo\perfecto-config.json 

    where CypressSEDemo is the name of the folder you created in step 1 | Install Cypress.

  2. Launch Perfecto and go to Test Analysis > Live Stream to view the live execution. When it is done, you can see the results based on the CI Job or Project, or you can open the report link that should appear in the command line window.

Following is a complete list of command line parameters, including the known reporting perfecto-cypress-sdk options to be passed.

Run command options
$ perfecto-cypress run --help
perfecto-cypress run

Run Cypress tests on Perfecto cloud

Credentials options (will override config file), --cloud          Cloud name                      [string]
  --credentials.securityToken, --token  Offline token                   [string]

Test options (will override config file)
  --tests.artifactKey, --ta  Repository artifact key                    [string]
  --tests.path, --tp         Root path for test to pack                 [string]
  --tests.ignore, --ti       ignore files list                           [array]
  --tests.specsExt, --ts     specs files extension
                                                 [string] [default: "*.spec.js"]

Reporting options (will override config file)
  --reporting.jobName, --rjn         reporting job name                 [string]
  --reporting.jobNumber, --rjNum     reporting job number               [number]
  --reporting.branch, --rb           reporting branch                   [string]
  --reporting.projectName, --rpn     reporting project name             [string]
  --reporting.projectVersion, --rpv  reporting project version          [string], --ra           reporting author                   [string]
  --reporting.tags, --rt             reporting tags, example: tag1 tag2  [array]
  --reporting.customFields, --rcf    reporting custom fields, example:
                                     key1,value1 key2,value2             [array]

  --env, -e     environment variables to attach to `cypress run` command
  --config, -c  Path to config file, see documentation:
                                             [default: "./perfecto-config.json"]

Note: We recommend that you pass the securityToken as a parameter instead of storing it in the perfecto-config.json file.

When uploading a Cypress test suite to the Perfecto cloud, utilize the following command options:

Upload command options
$ perfecto-cypress upload --help
perfecto-cypress upload

Upload tests zip archive to Perfecto cloud repository

Credentials options (will override config file), --cloud          Cloud name                      [string]
  --credentials.securityToken, --token  Offline token                   [string]

  --archivePath, -p  Path to tests zip file  [default: "./"]
  --temporary, -t    Upload tests archive as temp artifact
                                                       [boolean] [default: true]
  --folderType, -f   Set the location of tests archive in the repository
                    [choices: "PRIVATE", "PUBLIC", "GROUP"] [default: "PRIVATE"]
  --config, -c       Path to config file, see documentation:
                                             [default: "./perfecto-config.json"]

After uploading a .zip file to the cloud, the cloud admin should obtain the repository ID of that .zip file and pass it through the run command to be executed in the cloud. For example, if the repository ID is, the command would be as follows:

npx perfecto-cypress run --config=.\test\perfecto-config.json

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.

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

If you use TypeScript, make sure to change the pattern to: **/*.ts

Can be provided also as a CLI parameter

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

Supported values:
(We will use the lates release for the selected major version)

["6", "7", "8", "9", "10", "11", "12"]

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