cypress-io/eslint-plugin-cypress

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 or v10. Lower versions are no longer supported.

npm install eslint eslint-plugin-cypress --save-dev

or

yarn add eslint eslint-plugin-cypress --dev

Usage

ESLint as of v10 and this plugin no longer support the use of the deprecated eslintrc-type config file format. You must use a Flat config file format. This is the default in ESLint v9, and in ESLint v10 it is the only config format available.

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'

The configuration eslint-plugin-cypress/flat, which was deprecated in plugin version 5.0.0, is no longer available. Migrate to using the equivalent configuration eslint-plugin-cypress by dropping the /flat suffix.

Refer to ESLint v10 Configuration File Resolution for hierarchical use of configuration files.

Configurations

There are two specific configurations available:

Rules

These rules enforce some of the best practices recommended for using Cypress.

💼 Configurations enabled in.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.
❌ Deprecated.

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.

The examples use the defineConfig() helper, introduced with ESLint 9.22.0. Refer to the blog article Evolving flat config with extends for background information. If you are using ESLint <9.22.0, import defineConfig from @eslint/config-helpers instead of from eslint/config.

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

Cypress globals

The configs.globals are activated.

import { defineConfig } from 'eslint/config'
import pluginCypress from 'eslint-plugin-cypress'
export default defineConfig([
  {
    files: ['cypress/**/*.js'],
    extends: [pluginCypress.configs.globals],
  },
])

Typed Linting

You can activate typed linting for increased accuracy, if you want. This is purely optional and all rules continue to work without it. It uses a TypeScript parser to parse your entire project, instead of only the file being linted, which gives the plugin more information to work with. Be aware of the performance penalty that this brings with it.

First, install the @typescript-eslint/parser npm package:

npm install @typescript-eslint/parser --save-dev

If you already have a TypeScript codebase, you can skip the next step. If not, you need a tsconfig.json. The following minimal tsconfig.json does not compile or check your code and includes all .js files.

{
  "include": ["**/*.js"],
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "noEmit": true
  }
}

The last step is to extend your eslint config to use the typescript-eslint parser.

import { defineConfig } from 'eslint/config'
import typescriptParser from '@typescript-eslint/parser'
export default defineConfig([
  {
    languageOptions: {
      parser: typescriptParser,
      parserOptions: {
        projectService: true,
      },
    },
  },
])

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.

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 { defineConfig } from 'eslint/config'
import pluginMocha from 'eslint-plugin-mocha'
import pluginCypress from 'eslint-plugin-cypress'
export default defineConfig([
  {
    files: ['cypress/**/*.js'],
    extends: [
      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 { defineConfig } from 'eslint/config'
import pluginCypress from 'eslint-plugin-cypress'
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
export default defineConfig([
  {
    files: ['cypress/**/*.js'],
    extends: [
      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.