Prerequisites

The integration require that the following be installed:

• NodeJS
• Visual Studio Code
• IntelliJ IDEA

Network prerequisites

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

• <your-cloud>.app.perfectomobile.com

• <your-cloud>.perfectomobile.com/lab-execution

• 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

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:

• perfecto-config.json: See Perfecto config options.
• cypress.json: See the Cypress documentation.
• package.json: All dependencies that your project needs to execute the Cypress run command.

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 .perfectomobile.com.
   • 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.

   Help  Expand source

   $ perfecto-cypress --help
   perfecto-cypress <command>
   
   Commands:
     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
   
   Options:
     --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.

$ perfecto-cypress run --help
perfecto-cypress run

Run Cypress tests on Perfecto cloud

Credentials options (will override config file)
  --credentials.cloud, --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)
https://developers.perfectomobile.com/display/PD/Download+the+Reporting+SDK
  --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]
  --reporting.author, --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]

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

$ perfecto-cypress upload --help
perfecto-cypress upload

Upload tests zip archive to Perfecto cloud repository

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

Options:
  --archivePath, -p  Path to tests zip file  [default: "./perfecto-cypress.zip"]
  --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 PRIVATE:perfecto-cypress.zip, the command would be as follows:

npx perfecto-cypress run --config=.\test\perfecto-config.json --ta=PRIVATE:perfecto-cypress.zip

Perfecto-config.json details

credentials

{
  "cloud": "scouter",
  "securityToken": "***"
}

capabilities

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

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

tests.path

"./tests"

tests.ignore

[
  "**/cypress/logs/**",
  "**/cypress/videos/**",
  "**/cypress/screenshots/**",
  "**/unit-tests/**"
]

tests.specsExt

"**/*.cy.js"

nodeVersion

"12"

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

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

framework

"CYPRESS"

env

{
  "CYPRESS_BASE_URL": "https//my-ui-project.com/"
}

reporting

{
  "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": "sdet1@awesomecompany.com",
  "tags": [
    "espresso",
    "plugin"
  ]
}

"My Cypress project"

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.