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

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

   • perfecto-config.json: See Perfecto config options.
   • tests-folder/cypress.json: See the Cypress documentation.
   • tests-folder/package.json: All dependencies that your project needs to execute the Cypress run command.
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.

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

   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]
   

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.

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