Cypress ESLint Plugin
An ESLint plugin for your Cypress tests.
Note: If you installed ESLint globally then you must also install eslint-plugin-cypress
globally.
Installation
npm install eslint-plugin-cypress --save-dev
or
yarn add eslint-plugin-cypress --dev
Usage
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-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 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.
Rules with a check mark (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 | |
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 |
|
no-single-expect-in-then-or-should | Simplify tests by avoiding lonely expect() | |
no-expect-for-stub | Avoid expect(stub)… | |
no-useless-then-or-should | Avoid .should() and .then() when only wrapping commands |
no-unused-expressions
Chai and 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"]
}
Contribution Guide
To add a new rule:
- Fork and clone this repository
- Install dependencies with
npm install
- Generate a new rule with
npm run make-rule
- Run
yarn start
ornpm start
- Write test scenarios then implement logic
- Describe the rule in the generated
docs
file - Make sure all tests are passing
- Add the rule to this README
- Create a PR
Use the following commit message conventions: https://github.com/semantic-release/semantic-release#commit-message-format