An ESLint plugin for your Cypress tests.
Note: If you installed ESLint globally then you must also install
ESLint
You can add rules:
You can allow certain globals provided by Cypress:
Disable the
Disable the
Disable the
You can also disable a rule for the next line:
For more, see the ESLint rules documentation.
š¼ Configurations enabled in.\ ā Set in the
| Name | Description | š¼ | | :----------------------------------------------------------------------- | :--------------------------------------------------------- | :- | | assertion-before-screenshot | require screenshots to be preceded by an assertion | | | no-assigning-return-values | disallow assigning return values of
Mocha
During test spec development, Mocha exclusive tests
In your
Or you can simply use the
Chai and
Using an assertion such as
In your
Or you can simply add its
Note: If you installed ESLint globally then you must also install
eslint-plugin-cypress
globally.Installation
Prerequisites: ESLintv7
, v8
or v9
.
This plugin supports the use of Flat config files with ESLint 8.57.0
and above through @eslint/eslintrc.npm install eslint-plugin-cypress --save-dev
or
yarn add eslint-plugin-cypress --dev
Usage
If you are using ESLintv7
or v8
, then add an .eslintrc.json
file to the root directory of your Cypress project with the contents shown below. You can continue to use this format with ESLint v9
if you set the ESLINT_USE_FLAT_CONFIG
environment variable to false
(see ESLint v9 > Configuration Files (Deprecated).ESLint
v9
uses a Flat config file format with filename eslint.config.*js
by default. Please refer to additional Flat config installation and configuration details. (You may also use this with ESLint 8.57.0
.){
"plugins": [
"cypress"
]
}
You can add rules:
{
"rules": {
"cypress/no-assigning-return-values": "error",
"cypress/no-unnecessary-waiting": "error",
"cypress/assertion-before-screenshot": "warn",
"cypress/no-force": "warn",
"cypress/no-async-tests": "error",
"cypress/no-async-before": "error",
"cypress/no-pause": "error"
}
}
You can allow certain globals provided by Cypress:
{
"env": {
"cypress/globals": true
}
}
Recommended configuration
Use the recommended configuration and you can forego configuring plugins, rules, and env individually. See below for which rules are included.{
"extends": [
"plugin:cypress/recommended"
]
}
Disable rules
You can disable specific rules per file, for a portion of a file, or for a single line.Disable the
cypress/no-unnecessary-waiting
rule for the entire file by placing this at the start of the file:/* eslint-disable cypress/no-unnecessary-waiting */
Disable the
cypress/no-unnecessary-waiting
rule for only a portion of the file:it('waits for a second', () => {
...
/* eslint-disable cypress/no-unnecessary-waiting */
cy.wait(1000)
/* eslint-enable cypress/no-unnecessary-waiting */
...
})
Disable the
cypress/no-unnecessary-waiting
rule for a specific line:it('waits for a second', () => {
...
cy.wait(1000) // eslint-disable-line cypress/no-unnecessary-waiting
...
})
You can also disable a rule for the next line:
it('waits for a second', () => {
...
// eslint-disable-next-line cypress/no-unnecessary-waiting
cy.wait(1000)
...
})
For more, see the ESLint rules documentation.
Rules
These rules enforce some of the best practices recommended for using Cypress.š¼ Configurations enabled in.\ ā Set in the
recommended
configuration.| Name | Description | š¼ | | :----------------------------------------------------------------------- | :--------------------------------------------------------- | :- | | assertion-before-screenshot | require screenshots to be preceded by an assertion | | | no-assigning-return-values | disallow assigning return values of
cy
calls | ā
|
| no-async-before | disallow using async
/await
in Cypress before
methods | |
| no-async-tests | disallow using async
/await
in Cypress test cases | ā
|
| no-force | disallow using force: true
with action commands | |
| no-pause | disallow using cy.pause()
calls | |
| no-unnecessary-waiting | disallow waiting for arbitrary time periods | ā
|
| require-data-selectors | require data-*
attribute selectors | |
| unsafe-to-chain-command | disallow actions within chains | ā
|Mocha and Chai
Cypress is built on top of Mocha and Chai. See the following sections for information on using ESLint plugins eslint-plugin-mocha and eslint-plugin-chai-friendly together witheslint-plugin-cypress
.Mocha .only
and .skip
During test spec development, Mocha exclusive tests .only
or Mocha inclusive tests .skip
may be used to control which tests are executed, as described in the Cypress documentation Excluding and Including Tests. To apply corresponding rules, you can install and use eslint-plugin-mocha. The rule mocha/no-exclusive-tests detects the use of .only
and the mocha/no-skipped-tests rule detects the use of .skip
:npm install --save-dev eslint-plugin-mocha
In your
.eslintrc.json
:{
"plugins": [
"cypress",
"mocha"
],
"rules": {
"mocha/no-exclusive-tests": "warn",
"mocha/no-skipped-tests": "warn"
}
}
Or you can simply use the
cypress/recommended
and mocha/recommended
configurations together, for example:{
"extends": [
"plugin:cypress/recommended",
"plugin:mocha/recommended"
]
}
Chai and no-unused-expressions
Using an assertion such as expect(value).to.be.true
can fail the ESLint rule no-unused-expressions
even though it's not an error in this case. To fix this, you can install and use eslint-plugin-chai-friendly.npm install --save-dev eslint-plugin-chai-friendly
In your
.eslintrc.json
:{
"plugins": [
"cypress",
"chai-friendly"
],
"rules": {
"no-unused-expressions": 0,
"chai-friendly/no-unused-expressions": 2
}
}
Or you can simply add its
recommended
config:{
"extends": ["plugin:chai-friendly/recommended"]
}