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 (✅) 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
	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

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"]
}

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 or npm 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