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

Last updated: Feb 22, 2021 14:18

Note: This integration is currently in Beta phase and only available in select private clouds. If interested, 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

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

Cypress versions 3.8.3, 4.12.1, 5.6.0, and 6.3.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.

1 | Install Cypress

  1. Launch a terminal in your IDE.
  2. In the workspace folder, create a new folder, for example CypressSEDemo.
  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 new folder you created in step 1.

     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. Return to the workspace folder 'CypressSEDemo' by running the following command:

    cd ..
  2. Install the Perfecto-Cypress SDK by running the following command:

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

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

3 | Initialize the Perfecto-Cypress SDK

  1. Create the configuration files. 3 configuration files are required to run Cypress tests in Perfecto.

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

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

    Running the init command generates the following configuration files for you (if they do not exist):

  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.

    • 3.8.3
    • 4.12.1
    • 5.6.0
    • 6.0.1
  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]

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.

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

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
Note: We recommend that you pass the securityToken as a parameter instead of storing it in the perfecto-config.json file.

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. 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 (perfecto-config.json, cypress.json, and package.json).

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

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:
(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