eslint-plugin-cypress 3.1.0 → 3.2.0

package/FLAT-CONFIG.md

@@ -0,0 +1,134 @@
+# Cypress ESLint Plugin - Flat Config
+
+This document supplements the [README](README.md) 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](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/) 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](https://eslint.org/blog/2023/10/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 Cypress ESLint Plugin (`eslint-plugin-cypress`) is currently based on ESLint `8.x` and has not yet been migrated to support Flat Config natively. [ESLint's new config system, Part 2: Introduction to flat config](https://eslint.org/blog/2022/08/new-config-system-part-2/) from August 2022 introduced the [Backwards compatibility utility](https://eslint.org/blog/2022/08/new-config-system-part-2/#backwards-compatibility-utility). This gives the capability to use `eslint-plugin-cypress` in an ESLint flat config environment.
+
+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 [eslint@8.57.0](https://github.com/eslint/eslint/releases/tag/v8.57.0) or ESLint `9.x`.
+
+```shell
+npm install eslint @eslint/eslintrc eslint-plugin-cypress@^3.1.1 --save-dev
+```
+
+or
+
+```shell
+yarn add eslint @eslint/eslintrc eslint-plugin-cypress@^3.1.1 --dev
+```
+
+## Usage examples
+
+Add a flat configuration file `eslint.config.mjs` file to the root directory of your Cypress project. 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 the `FlatCompat` class of [@eslint/eslintrc](https://www.npmjs.com/package/@eslint/eslintrc).
+- [cypress/unsafe-to-chain-command](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/unsafe-to-chain-command.md) is active and set to `error`
+
+```js
+import { FlatCompat } from '@eslint/eslintrc'
+const compat = new FlatCompat()
+export default [
+  ...compat.config(
+    {
+      plugins: ['cypress'],
+      rules: {
+        'cypress/unsafe-to-chain-command': 'error'
+      }
+    })
+]
+```
+
+### Cypress recommended
+
+The `eslint-plugin-cypress` [recommended rules](README.md#rules) `plugin:cypress/recommended` are activated, except for
+- [cypress/no-unnecessary-waiting](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-unnecessary-waiting.md) set to `off`
+
+```js
+import { FlatCompat } from '@eslint/eslintrc'
+const compat = new FlatCompat()
+export default [
+  ...compat.config(
+    {
+      extends: ['plugin:cypress/recommended'],
+      rules: {
+        'cypress/no-unnecessary-waiting': 'off'
+      }
+    })
+]
+```
+
+### Cypress and Mocha recommended
+
+[eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) is added to the previous example. 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](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) and [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) are set to `error` instead of `warn`
+- [mocha/no-mocha-arrows](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-mocha-arrows.md) is set to `off` instead of `error`
+
+```shell
+npm install eslint-plugin-mocha@^10.4.3 --save-dev
+```
+
+```js
+import { FlatCompat } from '@eslint/eslintrc'
+import mochaPlugin from 'eslint-plugin-mocha'
+const compat = new FlatCompat()
+export default [
+  mochaPlugin.configs.flat.recommended, {
+    rules: {
+      'mocha/no-exclusive-tests': 'error',
+      'mocha/no-skipped-tests': 'error',
+      'mocha/no-mocha-arrows': 'off'
+    }
+  },
+  ...compat.config(
+    {
+      extends: ['plugin:cypress/recommended'],
+      rules: {
+        'cypress/no-unnecessary-waiting': 'off'
+      }
+    })
+]
+```
+
+### Cypress and Chai recommended
+
+[eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) is combined with the Cypress plugin `eslint-plugin-cypress`.
+
+The [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) plugin does not currently offer flat config options and so the `FlatCompat` class of [@eslint/eslintrc](https://www.npmjs.com/package/@eslint/eslintrc) enables this plugin to be used too. The recommended rules for both plugins are used: `plugin:cypress/recommended` and `plugin:chai-friendly/recommended`.
+
+```shell
+npm install eslint-plugin-chai-friendly --save-dev
+```
+
+```js
+import { FlatCompat } from '@eslint/eslintrc'
+const compat = new FlatCompat()
+export default [
+  ...compat.config(
+    {
+      extends: [
+        'plugin:cypress/recommended',
+        'plugin:chai-friendly/recommended'
+      ],
+      rules: {
+        'cypress/no-unnecessary-waiting': 'off',
+      }
+    })
+]
+```
+
+**Pending the resolution of issue https://github.com/ihordiachenko/eslint-plugin-chai-friendly/issues/32 [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) cannot be used with ESLint `v9`.**

package/README.md

@@ -6,7 +6,8 @@ Note: If you installed ESLint globally then you must also install `eslint-plugin
 
 ## Installation
 
-Prerequisites: [ESLint](https://www.npmjs.com/package/eslint) `v7` or `v8`. ESLint `v9` is **not** supported yet.
+Prerequisites: [ESLint](https://www.npmjs.com/package/eslint) `v7`, `v8` or `v9`.
+This plugin supports the use of [Flat config files](https://eslint.org/docs/latest/use/configure/configuration-files) with ESLint `8.57.0` and above through [@eslint/eslintrc](https://www.npmjs.com/package/@eslint/eslintrc).
 
 ```sh
 npm install eslint-plugin-cypress --save-dev
@@ -18,7 +19,9 @@ yarn add eslint-plugin-cypress --dev
 
 ## Usage
 
-Add an `.eslintrc.json` file to your `cypress` directory with the following:
+If you are using ESLint `v7` or `v8`, then add an `.eslintrc.json` file to the root directory of your Cypress project with the contents shown below. You can continue to use this format with ESLint `v9` if you set the `ESLINT_USE_FLAT_CONFIG` environment variable to `false` (see [ESLint v9 > Configuration Files (Deprecated)](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated).
+
+ESLint `v9` uses a [Flat config file](https://eslint.org/docs/latest/use/configure/configuration-files) format with filename `eslint.config.*js` by default. Please refer to [additional Flat config installation and configuration details](FLAT-CONFIG.md). (You may also use this with ESLint `8.57.0`.)
 
 ```json
 {

package/eslint.config.mjs

@@ -0,0 +1,27 @@
+import globals from 'globals'
+import pluginJs from '@eslint/js'
+import eslintPlugin from 'eslint-plugin-eslint-plugin'
+import nodePlugin from 'eslint-plugin-n'
+import mochaPlugin from 'eslint-plugin-mocha'
+
+export default [
+  pluginJs.configs.recommended,
+  eslintPlugin.configs['flat/recommended'],
+  nodePlugin.configs['flat/recommended-script'],
+  mochaPlugin.configs.flat.recommended,
+  {
+    languageOptions: {
+      globals: globals.node
+    },
+    rules: {
+      'no-redeclare': 'off',
+      'eslint-plugin/require-meta-docs-url':
+        ['error', { 'pattern': 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/{{name}}.md' }],
+      'eslint-plugin/require-meta-docs-description': 'error',
+      'n/no-extraneous-require':
+        ['error', { 'allowModules': ['jest-config'] }],
+      'mocha/no-mocha-arrows': 'off',
+      'mocha/no-setup-in-describe': 'off'
+    }
+  },
+]

package/lib/rules/unsafe-to-chain-command.js

@@ -19,7 +19,7 @@ const unsafeToChainActions = [
   'check',
   'dblclick',
   'each',
-  'focus$',
+  'focus',
   'rightclick',
   'screenshot',
   'scrollIntoView',
@@ -130,7 +130,7 @@ const isRootCypress = (node) => {
  */
 const isActionUnsafeToChain = (node, additionalMethods = []) => {
   const unsafeActionsRegex = new RegExp([
-    ...unsafeToChainActions,
+    ...unsafeToChainActions.map((action) => `^${action}$`),
     ...additionalMethods.map((method) => method instanceof RegExp ? method.source : method),
   ].join('|'))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-cypress",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "An ESLint plugin for projects using Cypress",
   "main": "index.js",
   "author": "Cypress-io",
@@ -19,16 +19,18 @@
   },
   "homepage": "https://github.com/cypress-io/eslint-plugin-cypress#readme",
   "peerDependencies": {
-    "eslint": ">=7 <9"
+    "eslint": ">=7"
   },
   "dependencies": {
     "globals": "^13.20.0"
   },
   "devDependencies": {
+    "@eslint/eslintrc": "^3.0.2",
+    "@eslint/js": "^9.2.0",
     "eslint": "^8.57.0",
-    "eslint-plugin-eslint-plugin": "^6.0.0",
+    "eslint-plugin-eslint-plugin": "^6.1.0",
     "eslint-plugin-mocha": "^10.4.3",
-    "eslint-plugin-n": "^17.2.1",
+    "eslint-plugin-n": "^17.4.0",
     "husky": "^9.0.11",
     "jest": "^29.7.0",
     "semantic-release": "23.0.8"

package/tests/lib/rules/unsafe-to-chain-command.js

@@ -18,6 +18,10 @@ ruleTester.run('action-ends-chain', rule, {
       code: 'cy.focused().should("be.visible");',
       parserOptions,
     },
+    {
+      code: 'cy.submitBtn().click();',
+      parserOptions,
+    },
   ],
 
   invalid: [

package/.eslintrc.js

@@ -1,30 +0,0 @@
-module.exports = {
-  "env": {
-    "node": true,
-    "es6": true
-  },
-  "plugins": [
-    "eslint-plugin",
-    "n",
-    "mocha"
-  ],
-  "extends": [
-    "eslint:recommended",
-    "plugin:eslint-plugin/recommended",
-    "plugin:n/recommended",
-    "plugin:mocha/recommended"
-  ],
-  "rules": {
-    "eslint-plugin/require-meta-docs-url":
-      ["error", { "pattern": "https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/{{name}}.md" }],
-    "eslint-plugin/require-meta-docs-description": "error",
-    "n/no-extraneous-require":
-      ["error", { "allowModules": ["jest-config"] }],
-    "no-redeclare": "off",
-    "mocha/no-mocha-arrows": "off",
-    "mocha/no-setup-in-describe": "off"
-  },
-  "parserOptions": {
-    "ecmaVersion": 2020
-  }
-}