Skip to content

cypress-io/eslint-plugin-cypress

Folders and files

NameName
Last commit message
Last commit date

Latest commit

874c51f Β· Sep 14, 2021
Sep 14, 2021
Sep 14, 2021
Sep 14, 2021
Jul 15, 2019
May 27, 2020
Sep 13, 2019
Sep 14, 2021
May 27, 2020
Sep 14, 2021
May 27, 2020
Jul 15, 2019
May 27, 2020

Repository files navigation

Cypress ESLint Plugin CircleCI

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.

NOTE: These rules currently require eslint 5.0 or greater. If you would like support added for eslint 4.x, please πŸ‘ this issue.

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

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
  • Generate a new rule (a yeoman generator is available)
  • 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