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 8.57.0 and 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.

Cypress ESLint Plugin (eslint-plugin-cypress) in release 3.2.0 offered the first support of ESLint 9.x flat config files using the Backwards compatibility utility. Current releases have removed the dependency on this utility and the examples in this document have been updated correspondingly.

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

Installation

It is recommended to use a minimum ESLint 8.x version [email protected] or 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. Additionally, languageOptions of ecmaVersion: 2019 and sourceType: 'module' for backwards compatibility with earlier versions of this plugin are defined. 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 [email protected] 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',
    },
  }
]