eslint-plugin-cypress 2.15.1 → 3.0.0

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run lint

package/.node-version

@@ -0,0 +1 @@
+20.12.2

package/.nvmrc

@@ -0,0 +1 @@
+20.12.2

package/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing to cypress-io/eslint-plugin-cypress
+
+Thanks for taking the time to contribute! :smile:
+
+To add a new rule:
+  * Fork and clone this repository
+  * Generate a new rule (a [yeoman generator](https://github.com/eslint/generator-eslint) is available)
+  * Write test scenarios then implement logic
+  * Describe the rule in the generated `docs` file
+  * Run `npm test` to run [Jest](https://jestjs.io/) or
+  * Run `npm start` to run [Jest](https://jestjs.io/) in [watchAll](https://jestjs.io/docs/cli#--watchall) mode where it remains active and reruns when source changes are made
+  * Make sure all tests are passing
+  * Add the rule to the [README](README.md) file
+  * Create a PR
+
+Use the following commit message conventions: https://github.com/semantic-release/semantic-release#commit-message-format

package/README.md

@@ -6,6 +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.
+
 ```sh
 npm install eslint-plugin-cypress --save-dev
 ```
@@ -36,6 +38,7 @@ You can add rules:
     "cypress/assertion-before-screenshot": "warn",
     "cypress/no-force": "warn",
     "cypress/no-async-tests": "error",
+    "cypress/no-async-before": "error",
     "cypress/no-pause": "error"
   }
 }
@@ -114,8 +117,6 @@ These rules enforce some of the [best practices recommended for using Cypress](h
 
 Rules with a check mark (✅) are enabled by default while using the `plugin:cypress/recommended` config.
 
-**NOTE**: These rules currently require eslint 5.0 or greater. If you would like support added for eslint 4.x, please 👍  [this issue](https://github.com/cypress-io/eslint-plugin-cypress/issues/14).
-
 |     | Rule ID                                                                    | Description                                                     |
 | :-- | :------------------------------------------------------------------------- | :-------------------------------------------------------------- |
 | ✅  | [no-assigning-return-values](./docs/rules/no-assigning-return-values.md)   | Prevent assigning return values of cy calls                     |
@@ -127,6 +128,44 @@ Rules with a check mark (✅) are enabled by default while using the `plugin:cyp
 |     | [require-data-selectors](./docs/rules/require-data-selectors.md)           | Only allow data-\* attribute selectors (require-data-selectors) |
 |     | [no-pause](./docs/rules/no-pause.md)           | Disallow `cy.pause()` parent command |
 
+## Mocha and Chai
+
+Cypress is built on top of [Mocha](https://on.cypress.io/guides/references/bundled-libraries#Mocha) and [Chai](https://on.cypress.io/guides/references/bundled-libraries#Chai). See the following sections for information on using ESLint plugins [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) and [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) together with `eslint-plugin-cypress`.
+
+## Mocha `.only` and `.skip`
+
+During test spec development, [Mocha exclusive tests](https://mochajs.org/#exclusive-tests) `.only` or [Mocha inclusive tests](https://mochajs.org/#inclusive-tests) `.skip` may be used to control which tests are executed, as described in the Cypress documentation [Excluding and Including Tests](https://on.cypress.io/guides/core-concepts/writing-and-organizing-tests#Excluding-and-Including-Tests). To apply corresponding rules, you can install and use [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha). The rule [mocha/no-exclusive-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) detects the use of `.only` and the [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) rule detects the use of `.skip`:
+
+```sh
+npm install --save-dev eslint-plugin-mocha
+```
+
+In your `.eslintrc.json`:
+
+```json
+{
+  "plugins": [
+    "cypress",
+    "mocha"
+  ],
+  "rules": {
+    "mocha/no-exclusive-tests": "warn",
+    "mocha/no-skipped-tests": "warn"
+  }
+}
+```
+
+Or you can simply use the `cypress/recommended` and `mocha/recommended` configurations together, for example:
+
+```json
+{
+  "extends": [
+    "plugin:cypress/recommended",
+    "plugin:mocha/recommended"
+  ]
+}
+```
+
 ## Chai and `no-unused-expressions`
 
 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](https://www.npmjs.com/package/eslint-plugin-chai-friendly).
@@ -158,16 +197,6 @@ Or you can simply add its `recommended` config:
 }
 ```
 
-## Contribution Guide
-
-To add a new rule:
-  * Fork and clone this repository
-  * Generate a new rule (a [yeoman generator](https://github.com/eslint/generator-eslint) is available)
-  * Run `yarn start` or `npm start`
-  * Write test scenarios then implement logic
-  * Describe the rule in the generated `docs` file
-  * Make sure all tests are passing
-  * Add the rule to this README
-  * Create a PR
+## Contributing
 
-Use the following commit message conventions: https://github.com/semantic-release/semantic-release#commit-message-format
+Please see our [Contributing Guideline](./CONTRIBUTING.md) which explains how to contribute rules or other fixes and features to the repo.

package/circle.yml

@@ -5,15 +5,13 @@ workflows:
   main:
     jobs:
       - lint
-      - test-v4
-      - test-v5
-      - test-v6
+      - test-v7
+      - test-v8
       - release:
           requires:
             - lint
-            - test-v4
-            - test-v5
-            - test-v6
+            - test-v7
+            - test-v8
           filters:
             branches:
               only:
@@ -22,60 +20,63 @@ workflows:
 jobs:
   lint:
     docker:
-      - image: circleci/node:16
+      - image: cimg/node:20.12.2
     steps:
       - checkout
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
+      - run:
+          name: Show ESLint version
+          command: npx eslint --version
       - run:
           name: Lint code
           command: npm run lint
 
-  test-v4:
+  test-v7:
     docker:
-      - image: circleci/node:16
+      - image: cimg/node:20.12.2
     steps:
       - checkout
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
       - run:
-          name: Test ESLint 4
-          command: npm run test:v4
-
-  test-v5:
-    docker:
-      - image: circleci/node:16
-    steps:
-      - checkout
+          name: Install ESLint 7
+          command: npm install eslint@7
       - run:
-          name: Install dependencies
-          command: npm install
+          name: Show ESLint version
+          command: npx eslint --version
       - run:
-          name: Test ESLint 5
-          command: npm run test
+          name: Test ESLint 7
+          command: npm test
 
-  test-v6:
+  test-v8:
     docker:
-      - image: circleci/node:16
+      - image: cimg/node:20.12.2
     steps:
       - checkout
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
+      - run:
+          name: Install ESLint 8
+          command: npm install eslint@8
+      - run:
+          name: Show ESLint version
+          command: npx eslint --version
       - run:
-          name: Test ESLint 6
-          command: npm run test:v6
+          name: Test ESLint 8
+          command: npm test
 
   release:
     docker:
-      - image: circleci/node:16
+      - image: cimg/node:20.12.2
     steps:
       - checkout
       - run:
           name: Install dependencies
-          command: npm install
+          command: npm ci
       - run:
           name: Run semantic release
           command: npm run semantic-release

package/docs/rules/no-async-before.md

@@ -0,0 +1,52 @@
+# Prevent using async/await in Cypress test cases (no-async-tests)
+
+Cypress commands that return a promise may cause side effects in before/beforeEach hooks, possibly causing unexpected behavior. 
+
+## Rule Details
+
+This rule disallows using `async` `before` and `beforeEach` functions.
+
+Examples of **incorrect** code for this rule:
+
+```js
+describe('my feature', () => {
+  before('my test case', async ()  => {
+    await cy.get('.myClass')
+    // other operations
+  })
+})
+```
+
+```js
+describe('my feature', () => {
+  before('my test case', async ()  => {
+    cy
+    .get('.myClass')
+    .click()
+
+    await someAsyncFunction()
+  })
+})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+describe('my feature', () => {
+  before('my test case', ()  => {
+    cy.get('.myClass')
+    // other operations
+  })
+})
+
+```
+
+## When Not To Use It
+
+If there are genuine use-cases for using `async/await` in your before then you may not want to include this rule (or at least demote it to a warning).
+
+## Further Reading
+
+- [Commands Are Asynchronous](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Asynchronous)
+- [Commands Are Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Promises)
+- [Commands Are Not Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Not-Promises)

package/lib/rules/no-async-before.js

@@ -0,0 +1,47 @@
+'use strict'
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Prevent using async/await in Cypress before methods',
+      category: 'Possible Errors',
+      recommended: true,
+    },
+    messages: {
+      unexpected: 'Avoid using async functions with Cypress before / beforeEach functions',
+    },
+  },
+
+  create (context) {
+    function isBeforeBlock (callExpressionNode) {
+      const { type, name } = callExpressionNode.callee
+
+      return type === 'Identifier'
+                && name === 'before' || name === 'beforeEach'
+    }
+
+    function isBeforeAsync (node) {
+      return node.arguments
+                && node.arguments.length >= 2
+                && node.arguments[1].async === true
+    }
+
+    return {
+      Identifier (node) {
+        if (node.name === 'cy' || node.name === 'Cypress') {
+          const ancestors = context.getAncestors()
+          const asyncTestBlocks = ancestors
+          .filter((n) => n.type === 'CallExpression')
+          .filter(isBeforeBlock)
+          .filter(isBeforeAsync)
+
+          if (asyncTestBlocks.length >= 1) {
+            asyncTestBlocks.forEach((node) => {
+              context.report({ node, messageId: 'unexpected' })
+            })
+          }
+        }
+      },
+    }
+  },
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-cypress",
-  "version": "2.15.1",
+  "version": "3.0.0",
   "description": "An ESLint plugin for projects using Cypress",
   "main": "index.js",
   "author": "Cypress-io",
@@ -19,34 +19,32 @@
   },
   "homepage": "https://github.com/cypress-io/eslint-plugin-cypress#readme",
   "peerDependencies": {
-    "eslint": ">= 3.2.1"
+    "eslint": ">=7 <9"
   },
   "dependencies": {
     "globals": "^13.20.0"
   },
   "devDependencies": {
-    "@cypress/eslint-plugin-dev": "3.2.0",
-    "@cypress/eslint-plugin-json": "3.2.1",
-    "condition-circle": "2.0.2",
-    "eslint": "^5.7.0",
-    "husky": "^3.0.0",
-    "jest": "^24.8.0",
-    "semantic-release": "15.13.18"
+    "@cypress/eslint-plugin-dev": "3.9.1",
+    "@cypress/eslint-plugin-json": "3.2.3",
+    "@typescript-eslint/eslint-plugin": "^4.33.0",
+    "@typescript-eslint/parser": "^4.33.0",
+    "eslint": "^7.32.0",
+    "eslint-plugin-mocha": "^6.3.0",
+    "husky": "^8.0.3",
+    "jest": "^29.7.0",
+    "semantic-release": "19.0.3"
+  },
+  "overrides": {
+    "eslint-plugin-mocha": "$eslint-plugin-mocha"
   },
   "scripts": {
-    "precommit": "npm run lint",
-    "lint": "eslint '*.js' '**/**/*.js'",
+    "lint": "eslint \"*.js\" \"**/**/*.js\"",
     "lint-fix": "npm run lint -- --fix",
     "semantic-release": "semantic-release",
-    "start": "yarn run test-watch",
+    "start": "npm run test-watch",
     "test": "jest",
-    "test:v4": "npm i eslint@4.x && npm run test",
-    "test:v6": "npm i eslint@6.x && npm run test",
-    "test-watch": "jest --watchAll"
-  },
-  "jest": {
-    "testMatch": [
-      "**/tests/**/*.js"
-    ]
+    "test-watch": "jest --watchAll",
+    "prepare": "husky install"
   }
 }

package/tests/lib/rules/no-async-before.js

@@ -0,0 +1,25 @@
+'use strict'
+
+const rule = require('../../../lib/rules/no-async-before')
+const RuleTester = require('eslint').RuleTester
+
+const ruleTester = new RuleTester()
+
+const errors = [{ messageId: 'unexpected' }]
+// async functions are an ES2017 feature
+const parserOptions = { ecmaVersion: 8 }
+
+ruleTester.run('no-async-before', rule, {
+  valid: [
+    { code: 'before(\'a before case\', () => { cy.get(\'.someClass\'); })', parserOptions },
+    { code: 'before(\'a before case\', async () => { await somethingAsync(); })', parserOptions },
+    { code: 'async function nonTestFn () { return await somethingAsync(); }', parserOptions },
+    { code: 'const nonTestArrowFn = async () => { await somethingAsync(); }', parserOptions },
+  ],
+  invalid: [
+    { code: 'before(\'a test case\', async () => { cy.get(\'.someClass\'); })', parserOptions, errors },
+    { code: 'beforeEach(\'a test case\', async () => { cy.get(\'.someClass\'); })', parserOptions, errors },
+    { code: 'before(\'a test case\', async function () { cy.get(\'.someClass\'); })', parserOptions, errors },
+    { code: 'beforeEach(\'a test case\', async function () { cy.get(\'.someClass\'); })', parserOptions, errors },
+  ],
+})