FLAT-CONFIG.md

Cypress ESLint Plugin - Flat Config

This document supplements the README document and describes how to use the Cypress ESLint Plugin (eslint-plugin-cypress) in an ESLint flat config environment.

Usage with ESLint 9.x is described.

Introduction

ESLint v9.0.0 was released on April 5, 2024, establishing flat config as the default for this version.

Previously, ESLint had announced in their blog post Flat config rollout plans in October 2023 that flat config was planned to be the default in ESLint v9.0.0 and that the eslintrc configuration system is planned to be removed in the future ESLint v10.0.0.

The following information details installation and usage examples for eslint-plugin-cypress together with related plugins in an ESLint flat config environment.

Installation

Use a minimum ESLint 9.x.

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

or

yarn add eslint eslint-plugin-cypress --dev

Usage examples

Add a flat configuration 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'

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)

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.

• cypress/unsafe-to-chain-command is active 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 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
]

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 of warn
• mocha/no-mocha-arrows is set to off instead of error

npm install eslint-plugin-mocha@^10.4.3 --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': 'warn',
      'mocha/no-skipped-tests': 'warn',
      'mocha/no-mocha-arrows': 'off',
      'cypress/no-unnecessary-waiting': 'off'
    }
  }
]

Cypress and Chai recommended

eslint-plugin-chai-friendly (minimum version eslint-plugin-chai-friendly@0.8.0 required for ESLint v9 support and flat config support) is combined with the Cypress plugin eslint-plugin-cypress.

The recommended rules for both plugins are used: pluginCypress.configs.recommended and pluginChaiFriendly.configs.recommended:

npm install eslint-plugin-chai-friendly@^0.8.0 --save-dev

import pluginCypress from 'eslint-plugin-cypress/flat'
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
export default [
  pluginCypress.configs.recommended,
  pluginChaiFriendly.configs.recommended,
  {
    rules: {
      'cypress/no-unnecessary-waiting': 'off',
    },
  }
]