Cypress Plugin
This page describes how to install, configure and use the Step plugin for Cypress. The Cypress plugin allows you to declare Step Keywords that run Cypress specs or commands and thus leverage the combined power of Step and Cypress.
Installation
The Cypress plugin is enabled by default for the Enterprise and SaaS versions of Step. To use the plugin you simply have to install Node.js on the Step Agents you’ll want to run Cypress Keywords on.
Usage
Declaring a Cypress Keyword
You can declare Cypress Keywords and use them within Plans like any other Step Keyword. To declare a Cypress Keyword:
- Navigate to the Keywords view
- Click “New keyword”
- Enter a name for your Keyword
- Select “Cypress” as Keyword type. If you don’t find “Cypress” in the list, you might be using the open-source edition (OS) of Step which doesn’t include the Cypress plugin
- Upload your Cypress project as zip
- Either enter the filename of the spec or the Cypress command to be called. You can call any generic Cypress command or custom command declared within your project. Example: cy.visit(“https://exense.ch”)
You may as well enter a list of commands using the text editor (pencil button) or in one line using a semicolon after each command
![](../../images/plugins/cypress/cypress-keyword-def_hu279249dcfafe35b91a5127518c71059d_418687_500x400_fit_q75_h2_catmullrom_3.webp)
Cypress project zip
The Cypress project has to be uploaded as a Zip to Step.
Considering the default folder structure of Cypress projects:
YourCypressProject
│ package.json
│ Cypress.config.js
└─── Cypress
└─── node_modules
Your project has to be zipped as follows:
zip -r YourCypressProject.zip YourCypressProject/
The zip of your project should contain either the package.json or the installed dependencies within node_modules.
- If the project contains a package.json, all dependencies will be installed prior to execute the Keyword and the versions of Cypress specified in the package.json will be used to run the Keyword
- If the project doesn’t contain a package.json but the node_modules, the Cypress version installed within the node_modules will be used to run the Keyword
- If the project contains neither a package.json nor the node_modules, the Cypress version 12.3.0 will be used to run the Keyword
Supported Cypress versions
The Cypress plugin supports Cypress versions up to 12.
It supports both JavaScript and TypeScript.
Creating a plan with Cypress Keywords
Creating a Plan with Cypress Keywords is as easy as with any other Keyword.
- Open Step
- Navigate to Plans
- Create a new Plan
- Select your Cypress Keywords from the Keyword list and add them to the plan
![](../../images/plugins/cypress/cypress-plan-def_huc209fcf66eb7dbd1e7f1d89e0b3ba669_271779_500x400_fit_q75_h2_catmullrom_3.webp)
You can create a sequence of Cypress Keywords within your plan. The Keywords and thus the corresponding Cypress commands will be executed sequentially. Step waits synchronously for each command to terminate before running the next command.
If the Keywords are put in a Test Case or a Session control, the commands will be executed within the same Cypress session
Passing input to Cypress keywords
Keyword input are supported only for Cypress keywords running entire cypress spec file. It works the same way as any other keyword.
To use the inputs in your cypress script simply refer to them with Step.input.<inputKey>
Example:
it('Exense_Home', () => {
cy.Exense_Home();
cy.Exense_Home_with_input_assertions();
if(Step.input.myString != 'myStringValue' || Step.input.myNumber != 10 || Step.input.myBoolean != true) {
throw new Error('Step Keyword input missing. Input was:' + JSON.stringify(Step.input))
}
})
Running a plan with Cypress Keywords
Once you’ve created your Plan, run it by clicking on the Play button as documented here
The execution report looks the same as with other Keywords. If the Parameter debug is to true a screenshot will be generated after each Keyword execution.
![](../../images/plugins/cypress/cypress-plan-execution_hu1f495e602b1bb84f0395933760384f81_331032_500x400_fit_q75_h2_catmullrom_3.webp)
In addition to the measurement of the whole Keyword response time, a performance measurement for each Cypress command is generated and can be analyzed under the Performance tab
![](../../images/plugins/cypress/cypress-plan-execution-performance_hu1f495e602b1bb84f0395933760384f81_348639_500x400_fit_q75_h2_catmullrom_3.webp)
![](../../images/plugins/cypress/cypress-plan-execution-performance-2_hu1f495e602b1bb84f0395933760384f81_338887_500x400_fit_q75_h2_catmullrom_3.webp)
Limitations
In its current version the Cypress plugin has following limitation:
- Keyword outputs are not supported
- Keyword inputs are only supported for Keyword running Spec file, support of inputs for keywords running cypress commands will be added soon