Automation with Cypress

Test reference in SquashTM

In order to bind a SquashTM test case to a Cypress automated test, the content of the Automated test reference field of the Automation block of a test case must have the following format:

[repository]/[project]#[test_file]
or
[repository]#[test_file]
(The reference always contains a single # character.)

with:

[repository]: Name of the Git repository.
[project]: Path to the Cypress project directory, i.e. the directory containing the cypress.json/cypress.config.js file and the cypress directory.
This parameter is optional, i.e. if the Cypress project is at the root of the Git repository, this path is absent.
[test_file]: Path (relative to the previous directory) and name of the Cypress test file, from the root of the project (with the .spec.js extension).

Example 1: my_repo/projects/second_project#cypress/integration/actions.spec.js (the Cypress project is in a subfolder)

Example 2: my_repo#cypress/integration/actions.spec.js (the Cypress project is at the root of the repository)

Old syntax

Old versions of SquashTM Orchestrator used the following format:

[repository]/[test_file]

with:

[repository]: Name of the Git repository.
[test_file]: Path and name of the Cypress test file, from the root of the project (with the .spec.js extension).

Example: my_repo/cypress/integration/actions.spec.js

This syntax is deprecated and should not be used. It is nevertheless still supported.
This syntax did not support Cypress tests which are not at the root of the source code repository.

Determination of the result of the test case

In this version of SquashTM, it is not possible to select a specific test in a .spec.js file containing several ones: all tests in the file are therefore executed together.
The result of the SquashTM test case is calculated by taking into account the individual results of each test included in the .spec.js file:

If at least one test has an Error status (in case of a technical issue), the status of the execution will be Blocked.
If at least one test fails functionally and none of the other ones has an Error status, the status of the execution will be Failed.
If all tests succeed, the status of the execution will be Success.

Nature of the exploitable SquashTM parameters

The exploitable SquashTM parameters will differ depending on whether you're using the Community/Premium or Ultimate version of SquashTM.

Here is a table showing the exploitable parameters (these parameters are transmitted as test parameters, see below, SquashTM does not generate global parameters):

Nature	Key	Community/Premium	Ultimate
Name of the dataset	`DSNAME`	✅	✅
Dataset parameter	`DS_[name]`	✅	✅
Execution ID	`TC_EXECUTION_ID`	❌	✅
Test case reference	`TC_REFERENCE`	✅	✅
Test case internal UUID	`TC_UUID`	✅	✅
Test case custom field	`TC_CUF_[code]`	✅	✅
Iteration custom field	`IT_CUF_[code]`	❌	✅
Campaign custom field	`CPG_CUF_[code]`	❌	✅
Test suite custom field	`TS_CUF_[code]`	❌	✅

Legend:

[code]: Value of the "Code" of a custom field
[name]: Name of a datasset

As indicated, SquashTM adds a prefix to the code of the transmitted custom field. Make sure to take it into account.

Availability of the execution ID

TC_EXECUTION_ID is only available with Squash TM 8.0 or later.

Parameters usage

It is possible, when running Cypress tests, to exploit parameters within it. A parameter can be a test parameter or a global parameter. SquashTM transmits only test parameters. Test parameters and global parameters can be used in the case of a launch from a CI/CD pipeline with the cypress/params action.

The parameters are available as CYPRESS_VAR environment variables and can be retrieved using the Cypress.env('VAR') syntax (see the Cypress documentation). If the same name is used both for a global parameter and a test parameter, the last one is used.

Example

Below is an example of a Cypress test file and the corresponding SquashTM test case automation:

Cypress example

Adding parameters to the test launch command line

You can pass additional parameters to the cypress run command using the CYPRESS_EXTRA_OPTIONS environment variable. Here is an example of how to define an environment variable in SquashTM and associate it with the orchestrator.

Some parameters are already defined in the cypress run command used to launch tests:

cypress run \
  --project "{project_path}" --spec "{spec_path}" \
  --config screenshotsFolder="{screenshots_folder_uuid}" --reporter junit \
  --reporter-options "mochaFile={report_file_path}" $CYPRESS_EXTRA_OPTIONS

You must avoid passing, via the CYPRESS_EXTRA_OPTIONS variable, the command line parameters that conflict with the parameters already used, or the parameters that impact the generation or alter the path of the reports expected by the orchestrator (view the report list).

Non-support of the space character on Linux

SquashTM Orchestrator currently does not support the space character () in the CYPRESS_EXTRA_OPTIONS environment variable for tests executed in a Linux execution environment.

Supported versions

SquashTM has been validated with the following versions of Cypress. More recent versions should work properly.

Testing Technology	Version
Cypress	12.12.0