eslint-plugin-cypress
v4.1.0
Published
An ESLint plugin for projects using Cypress
Downloads
13,458,823
Readme
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
Prerequisites: ESLint v9
. Lower versions are no longer supported.
npm install eslint eslint-plugin-cypress --save-dev
or
yarn add eslint eslint-plugin-cypress --dev
Usage
ESLint v9
uses a Flat config file format with filename eslint.config.*js
by default. For instructions on using a deprecated eslintrc-type config file from previous ESLint versions, please refer to the ESLINTRC-CONFIG document.
To set up a flat configuration, add a file eslint.config.mjs
to the root directory of your Cypress project and include the following instructions to import the available flat configurations using:
import pluginCypress from 'eslint-plugin-cypress/flat'
Configurations
There are two specific flat configurations available:
| Configuration | Content |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| configs.globals
| defines globals cy
, Cypress
, expect
, assert
and chai
used in Cypress test specs as well as globals.browser
and globals.mocha
from globals. This version no longer specifies languageOptions
for ecmaVersion
and sourceType
- see ESLint JavaScript languageOptions. There are no default rules enabled in this configuration. |
| configs.recommended
| enables recommended Rules. It includes also configs.global
(see above). |
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-debug | disallow using cy.debug()
calls | |
| 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 | ✅ |
Usage examples
In the following sections, different examples of possible configuration file contents are given, together with some brief explanations. Adapt these examples according to your needs.
Cypress
All rules from eslint-plugin-cypress
are available through eslint-plugin-cypress/flat
and can be individually activated.
- cypress/unsafe-to-chain-command is activated and set to
error
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
{
plugins: {
cypress: pluginCypress
},
rules: {
'cypress/unsafe-to-chain-command': 'error'
}
}
]
Cypress recommended
The eslint-plugin-cypress
recommended rules configs.recommended
are activated, except for
- cypress/no-unnecessary-waiting which is set to
off
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
pluginCypress.configs.recommended,
{
rules: {
'cypress/no-unnecessary-waiting': 'off'
}
}
]
Cypress globals
The configs.globals
are activated.
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
pluginCypress.configs.globals
]
Disable rules
You can disable specific rules per file, for a portion of a file, or for a single line. See the ESLint rules documentation. For example ...
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)
...
})
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 with eslint-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
.
Cypress and Mocha recommended
eslint-plugin-mocha is added to the example Cypress recommended. This plugin offers a flat file recommended option configs.flat.recommended
.
The settings for individual mocha
rules from the configs.flat.recommended
option are changed.
- mocha/no-exclusive-tests and mocha/no-skipped-tests are set to
error
instead ofwarn
- mocha/no-mocha-arrows is set to
off
instead oferror
npm install eslint-plugin-mocha@^10.5.0 --save-dev
import pluginMocha from 'eslint-plugin-mocha'
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
pluginMocha.configs.flat.recommended,
pluginCypress.configs.recommended,
{
rules: {
'mocha/no-exclusive-tests': 'error',
'mocha/no-skipped-tests': 'error',
'mocha/no-mocha-arrows': 'off',
'cypress/no-unnecessary-waiting': 'off'
}
}
]
Cypress and Chai 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.
eslint-plugin-chai-friendly is combined with the Cypress plugin eslint-plugin-cypress
.
The recommended rules for both plugins are used: pluginCypress.configs.recommended
and pluginChaiFriendly.configs.recommendedFlat
:
npm install eslint-plugin-chai-friendly@^1.0.1 --save-dev
import pluginCypress from 'eslint-plugin-cypress/flat'
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
export default [
pluginCypress.configs.recommended,
pluginChaiFriendly.configs.recommendedFlat,
{
rules: {
'cypress/no-unnecessary-waiting': 'off',
},
}
]
Contributing
Please see our Contributing Guideline which explains how to contribute rules or other fixes and features to the repo.