An ESLint plugin for your Cypress tests.
Note: If you installed ESLint globally then you must also install eslint-plugin-cypress
globally.
Prerequisites: ESLint v7
or v8
. ESLint v9
is not supported yet.
npm install eslint-plugin-cypress --save-dev
or
yarn add eslint-plugin-cypress --dev
Add an .eslintrc.json
file to your cypress
directory with the following:
{
"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
}
}
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"
]
}
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.
These rules enforce some of the best practices recommended for using Cypress.
Rules with a check mark (β
) are enabled by default while using the plugin:cypress/recommended
config.
Rule ID | Description | |
---|---|---|
β | no-assigning-return-values | Prevent assigning return values of cy calls |
β | no-unnecessary-waiting | Prevent waiting for arbitrary time periods |
β | no-async-tests | Prevent using async/await in Cypress test case |
β | unsafe-to-chain-command | Prevent chaining from unsafe to chain commands |
no-force | Disallow using force: true with action commands |
|
assertion-before-screenshot | Ensure screenshots are preceded by an assertion | |
require-data-selectors | Only allow data-* attribute selectors (require-data-selectors) | |
no-pause | Disallow cy.pause() parent command |
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 with eslint-plugin-cypress
.
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"
]
}
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"]
}
Please see our Contributing Guideline which explains how to contribute rules or other fixes and features to the repo.