eslint-plugin-cypress

What is eslint-plugin-cypress?

The eslint-plugin-cypress npm package provides a set of linting rules specific to Cypress, an end-to-end testing framework. These rules help developers adhere to best practices and avoid common mistakes when writing Cypress tests.

What are eslint-plugin-cypress's main functionalities?

Enforcing Assertions

Ensures that assertions are made in test cases to prevent tests that mistakenly pass without asserting any conditions.

expect(something).to.be.true;

Disallowing Assignment in Conditional Expressions

Prevents the use of assignment operators in conditional expressions, which can lead to tests that pass incorrectly due to an assignment rather than a proper comparison.

if (user = getUser()) { /* ... */ }

Disallowing Unnecessary Waiting

Discourages the use of arbitrary wait times in tests, promoting the use of Cypress's built-in waiting mechanisms that are more reliable and efficient.

cy.wait(5000);

Other packages similar to eslint-plugin-cypress

eslint-plugin-jest

This package provides linting rules for Jest, another popular testing framework. It is similar to eslint-plugin-cypress in that it offers a set of rules tailored to the specific testing framework to encourage best practices.

eslint-plugin-mocha

Similar to eslint-plugin-cypress, this package offers linting rules for Mocha, a test framework for Node.js and the browser. It helps maintain code quality and adherence to Mocha-specific conventions.

eslint-plugin-testing-library

This package is designed for linting code that uses the Testing Library family of utilities. It provides rules that help enforce best practices when writing tests with Testing Library, similar to how eslint-plugin-cypress does for Cypress tests.

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. This plugin no longer supports the use of a deprecated eslintrc-type config file from previous ESLint versions.

To set up a configuration, add a file eslint.config.mjs to the root directory of your Cypress project and include the following instructions to import the available configurations using:

import pluginCypress from 'eslint-plugin-cypress'

For backwards compatibility with previous plugin versions 3.3.0 - 4.3.0, the following equivalent deprecated form is also supported. This is planned to be removed in a future major version:

import pluginCypress from 'eslint-plugin-cypress/flat' # deprecated

Configurations

There are two specific 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. 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-chained-get	disallow chain of cy.get() calls
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	✅
no-xpath	disallow using cy.xpath() calls
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 are available by importing from eslint-plugin-cypress and can be individually activated.

• cypress/unsafe-to-chain-command is activated and set to error

import pluginCypress from 'eslint-plugin-cypress'
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'
export default [
  pluginCypress.configs.recommended,
  {
    rules: {
      'cypress/no-unnecessary-waiting': 'off'
    }
  }
]

Cypress globals

The configs.globals are activated.

import pluginCypress from 'eslint-plugin-cypress'
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@^11 plugin version or above. The rule mocha/no-exclusive-tests detects the use of .only and the mocha/no-pending-tests rule detects the use of .skip.

Cypress and Mocha recommended

eslint-plugin-mocha@^11 is added to the example Cypress recommended. This version of the plugin supports only flat file configurations with the option configs.recommended.

The settings for individual mocha rules from the configs.recommended option are changed.

• mocha/no-exclusive-tests and mocha/no-pending-tests are set to error instead of warn
• mocha/no-mocha-arrows is set to off instead of error

npm install eslint-plugin-mocha@^11 --save-dev

import pluginMocha from 'eslint-plugin-mocha'
import pluginCypress from 'eslint-plugin-cypress'
export default [
  pluginMocha.configs.recommended,
  pluginCypress.configs.recommended,
  {
    rules: {
      'mocha/no-exclusive-tests': 'error',
      'mocha/no-pending-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'
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.