eslint-plugin-cypress 4.2.0 → 4.3.0

package/CONTRIBUTING.md

@@ -48,3 +48,29 @@ This plugin uses the ESLint [eslint-doc-generator](https://www.npmjs.com/package
 
 * The directory [tests-legacy](https://github.com/cypress-io/eslint-plugin-cypress/tree/master/tests-legacy) contains tests which are compatible with the legacy [ESLint v8 RuleTester](https://eslint.org/docs/v8.x/integrate/nodejs-api#ruletester) utility. It is not expected to add new rules to this set of tests.
 * The directory [tests](https://github.com/cypress-io/eslint-plugin-cypress/tree/master/tests) is for tests compatible with the current [ESLint RuleTester](https://eslint.org/docs/latest/integrate/nodejs-api#ruletester).
+
+## Merging pull requests
+
+This information is for Cypress.io Members or Collaborators who merge pull requests:
+
+1. When merging a pull request, use the [Squash and merge](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github#squashing-your-merge-commits) option to squash all commits into one.
+1. Make sure the commit subject and body follow [semantic commit convention](https://semantic-release.gitbook.io/semantic-release/#commit-message-format), for instance:
+
+   ```text
+   feat: added new parameter
+   fix: fixed a bug
+   ```
+
+   If you need to bump the major version, mark it as breaking change in the body of the commit's message like:
+
+   ```text
+   fix: upgrade dependency X
+
+   BREAKING CHANGE: requires minimum Node.js 20 to run
+   ```
+
+1. New versions of this module will be released automatically by the CI pipeline when any PR with a triggering commit message is merged to the `master` branch: see the `release` job of [circle.yml](circle.yml).
+This will create a new [GitHub release](https://github.com/cypress-io/eslint-plugin-cypress/releases) and publish it to [eslint-plugin-cypress](https://www.npmjs.com/package/eslint-plugin-cypress) on the [npm registry](https://docs.npmjs.com/about-the-public-npm-registry).
+1. The module's CI is configured to use the [default Angular release rules](https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-rules.js).
+This means that only `feat:`, `fix:` and `perf:` trigger a new release.
+Other Angular commit types listed in the [Angular commit message guidelines](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md) can be used for documentation purposes, however they are ignored by the currently configured release process.

package/README.md

@@ -50,6 +50,7 @@ These rules enforce some of the [best practices recommended for using Cypress](h
 | [no-assigning-return-values](docs/rules/no-assigning-return-values.md)   | disallow assigning return values of `cy` calls             | ✅  |
 | [no-async-before](docs/rules/no-async-before.md)                         | disallow using `async`/`await` in Cypress `before` methods |    |
 | [no-async-tests](docs/rules/no-async-tests.md)                           | disallow using `async`/`await` in Cypress test cases       | ✅  |
+| [no-chained-get](docs/rules/no-chained-get.md)                           | disallow chain of `cy.get()` calls                         |    |
 | [no-debug](docs/rules/no-debug.md)                                       | disallow using `cy.debug()` calls                          |    |
 | [no-force](docs/rules/no-force.md)                                       | disallow using `force: true` with action commands          |    |
 | [no-pause](docs/rules/no-pause.md)                                       | disallow using `cy.pause()` calls                          |    |

package/circle.yml

@@ -1,17 +1,37 @@
 version: 2.1
 
+executors:
+  docker-executor:
+    docker:
+      - image: cimg/node:22.14.0
+    resource_class: medium
+
 workflows:
-  version: 2.1
   main:
     jobs:
       - lint
       - test-v8
       - test-v9
+
+      - build-test-project
+      - test-test-project:
+          matrix:
+            parameters:
+              eslint-version: ['9']
+              config-file: [
+                  # configurations correspond to examples in README
+                  'default',
+                  'recommended',
+                  'globals',
+                ]
+          requires:
+            - build-test-project
       - release:
           requires:
             - lint
             - test-v8
             - test-v9
+            - test-test-project
           filters:
             branches:
               only:
@@ -19,8 +39,7 @@ workflows:
 
 jobs:
   lint:
-    docker:
-      - image: cimg/node:22.11.0
+    executor: docker-executor
     steps:
       - checkout
       - run:
@@ -34,8 +53,7 @@ jobs:
           command: npm run lint
 
   test-v8:
-    docker:
-      - image: cimg/node:22.11.0
+    executor: docker-executor
     steps:
       - checkout
       - run:
@@ -52,8 +70,7 @@ jobs:
           command: npm run test:legacy
 
   test-v9:
-    docker:
-      - image: cimg/node:22.11.0
+    executor: docker-executor
     steps:
       - checkout
       - run:
@@ -69,9 +86,65 @@ jobs:
           name: Test ESLint 9
           command: npm test
 
+  build-test-project:
+    executor: docker-executor
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: npm ci
+      - run:
+          name: Build tarball
+          command: npm pack
+      - run:
+          name: Get version
+          command: |
+            echo "PLUGIN_VERSION=$(jq -r '.version' package.json)" >> $BASH_ENV
+            cp $BASH_ENV bash.env
+      - persist_to_workspace:
+          root: .
+          paths:
+            - eslint-plugin-cypress-*.tgz
+            - bash.env
+
+  test-test-project:
+    description: Run ESLint with different configurations
+    parameters:
+      eslint-version:
+        description: Version of ESLint to use
+        default: 'latest'
+        type: string
+      config-file:
+        description: Configuration file
+        default: 'default'
+        type: string
+    executor: docker-executor
+    working_directory: ./test-project
+    steps:
+      - checkout:
+          path: ../
+      - attach_workspace:
+          at: .
+      - run:
+          name: Get plugin version
+          command: |
+            cat bash.env >> $BASH_ENV
+      - run:
+          name: Install dependencies
+          command: |
+            npm install eslint@<< parameters.eslint-version>> ./eslint-plugin-cypress-$PLUGIN_VERSION.tgz -D
+      - run:
+          name: Display ESLint version
+          command: |
+            npx eslint --version
+      - run: echo Testing a << parameters.config-file >> configuration
+      - run:
+          name: Lint with example configuration
+          command: |
+            npx eslint --config ./eslint-configs/eslint.<< parameters.config-file >>.mjs .
+
   release:
-    docker:
-      - image: cimg/node:22.11.0
+    executor: docker-executor
     steps:
       - checkout
       - run:

package/docs/rules/no-chained-get.md

@@ -0,0 +1,19 @@
+# Disallow chain of `cy.get()` calls (`cypress/no-chained-get`)
+
+<!-- end auto-generated rule header -->
+This rule disallows the usage of chained `.get()` calls as `cy.get()` always starts its search from the cy.root element.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```js
+cy.get('parent').get('child')
+```
+
+Examples of **correct** code for this rule:
+
+```js
+cy.get('parent')
+  .find('child')
+```

package/eslint.config.mjs

@@ -7,6 +7,7 @@ export default [
   pluginJs.configs.recommended,
   eslintPlugin.configs['flat/recommended'],
   mochaPlugin.configs.flat.recommended,
+  {ignores: ['test-project/']},
   {
     languageOptions: {
       globals: globals.node

package/legacy.js

@@ -13,6 +13,7 @@ module.exports = {
     'no-pause': require('./lib/rules/no-pause'),
     'no-debug': require('./lib/rules/no-debug'),
     'no-xpath': require('./lib/rules/no-xpath'),
+    'no-chained-get': require('./lib/rules/no-chained-get'),
   },
   configs: {
     recommended: require('./lib/config/recommended'),

package/lib/flat.js

@@ -16,6 +16,7 @@ const plugin = {
     'no-pause': require('./rules/no-pause'),
     'no-debug': require('./rules/no-debug'),
     'no-xpath': require('./rules/no-xpath'),
+    'no-chained-get': require('./rules/no-chained-get'),
   },
 }
 

package/lib/rules/no-chained-get.js

@@ -0,0 +1,87 @@
+'use strict';
+
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow chain of `cy.get()` calls',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-chained-get.md',
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      unexpected: 'Avoid chaining multiple cy.get() calls',
+    },
+  },
+
+  create(context) {
+    const isRootCypress = (node) => {
+      if (
+        node.type !== 'CallExpression' ||
+        node.callee.type !== 'MemberExpression'
+      ) {
+        return false;
+      }
+
+      if (
+        node.callee.object.type === 'Identifier' &&
+        node.callee.object.name === 'cy'
+      ) {
+        return true;
+      }
+
+      return isRootCypress(node.callee.object);
+    };
+
+    const hasChainedGet = (node) => {
+      // Check if this node is a get() call
+      const isGetCall =
+        node.callee &&
+        node.callee.type === 'MemberExpression' &&
+        node.callee.property &&
+        node.callee.property.type === 'Identifier' &&
+        node.callee.property.name === 'get';
+
+      if (!isGetCall) {
+        return false;
+      }
+
+      const obj = node.callee.object;
+
+      if (obj.type === 'CallExpression') {
+        const objCallee = obj.callee;
+
+        if (
+          objCallee &&
+          objCallee.type === 'MemberExpression' &&
+          objCallee.property &&
+          objCallee.property.type === 'Identifier' &&
+          objCallee.property.name === 'get'
+        ) {
+          return true;
+        }
+
+        return hasChainedGet(obj);
+      }
+
+      return false;
+    };
+
+    return {
+      CallExpression(node) {
+        if (isRootCypress(node) && hasChainedGet(node)) {
+          context.report({
+            node,
+            messageId: 'unexpected',
+          });
+        }
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-cypress",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "An ESLint plugin for projects using Cypress",
   "main": "legacy.js",
   "exports": {
@@ -26,15 +26,15 @@
     "eslint": ">=9"
   },
   "dependencies": {
-    "globals": "^15.11.0"
+    "globals": "^15.15.0"
   },
   "devDependencies": {
-    "eslint": "^9.13.0",
-    "eslint-plugin-eslint-plugin": "^6.3.1",
+    "eslint": "^9.24.0",
+    "eslint-plugin-eslint-plugin": "^6.4.0",
     "eslint-plugin-mocha": "^10.5.0",
-    "husky": "^9.1.6",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
-    "semantic-release": "24.2.0"
+    "semantic-release": "24.2.3"
   },
   "scripts": {
     "lint": "eslint \"*.js\" \"**/**/*.js\"",

package/test-project/README.md

@@ -0,0 +1,48 @@
+# Test-project
+
+This test project was generated via the Cypress App.
+
+This project can be updated to the latest Cypress default scaffolded E2E test specs by carrying out the following steps in the directory `/test-project`:
+
+```shell
+rm -rf cypress cypress.config.js
+npm install cypress@latest --no-package-lock
+npx cypress open
+```
+
+- Select "Continue" for "What's New in Cypress" if displayed
+- Select "E2E Testing"
+- Select "Continue" in "Configuration files"
+- Select "Electron" browser
+- Select "Start E2E Testing in Electron"
+- Select "Scaffold example specs"
+- Close all Cypress windows
+
+Test that scaffolded specs run:
+
+```shell
+npm test
+```
+
+Remove Cypress from `package.json`:
+
+```shell
+npm uninstall cypress --no-package-lock
+```
+
+## Tests
+
+Tests are run via [circle.yml](../circle.yml).
+
+To test the project locally:
+
+```shell
+cd test-project
+npm install eslint@latest eslint-plugin-cypress@latest cypress@latest -D
+npx cypress run
+npx eslint
+```
+
+Do not commit the changes from installing the above dependencies.
+The CircleCI pipeline dynamically installs the latest `eslint*` dependencies.
+Cypress is not needed for the CircleCI tests.

package/test-project/cypress/e2e/1-getting-started/todo.cy.js

@@ -0,0 +1,143 @@
+/// <reference types="cypress" />
+
+// Welcome to Cypress!
+//
+// This spec file contains a variety of sample tests
+// for a todo list app that are designed to demonstrate
+// the power of writing tests in Cypress.
+//
+// To learn more about how Cypress works and
+// what makes it such an awesome testing tool,
+// please read our getting started guide:
+// https://on.cypress.io/introduction-to-cypress
+
+describe('example to-do app', () => {
+  beforeEach(() => {
+    // Cypress starts out with a blank slate for each test
+    // so we must tell it to visit our website with the `cy.visit()` command.
+    // Since we want to visit the same URL at the start of all our tests,
+    // we include it in our beforeEach function so that it runs before each test
+    cy.visit('https://example.cypress.io/todo')
+  })
+
+  it('displays two todo items by default', () => {
+    // We use the `cy.get()` command to get all elements that match the selector.
+    // Then, we use `should` to assert that there are two matched items,
+    // which are the two default items.
+    cy.get('.todo-list li').should('have.length', 2)
+
+    // We can go even further and check that the default todos each contain
+    // the correct text. We use the `first` and `last` functions
+    // to get just the first and last matched elements individually,
+    // and then perform an assertion with `should`.
+    cy.get('.todo-list li').first().should('have.text', 'Pay electric bill')
+    cy.get('.todo-list li').last().should('have.text', 'Walk the dog')
+  })
+
+  it('can add new todo items', () => {
+    // We'll store our item text in a variable so we can reuse it
+    const newItem = 'Feed the cat'
+
+    // Let's get the input element and use the `type` command to
+    // input our new list item. After typing the content of our item,
+    // we need to type the enter key as well in order to submit the input.
+    // This input has a data-test attribute so we'll use that to select the
+    // element in accordance with best practices:
+    // https://on.cypress.io/selecting-elements
+    cy.get('[data-test=new-todo]').type(`${newItem}{enter}`)
+
+    // Now that we've typed our new item, let's check that it actually was added to the list.
+    // Since it's the newest item, it should exist as the last element in the list.
+    // In addition, with the two default items, we should have a total of 3 elements in the list.
+    // Since assertions yield the element that was asserted on,
+    // we can chain both of these assertions together into a single statement.
+    cy.get('.todo-list li')
+      .should('have.length', 3)
+      .last()
+      .should('have.text', newItem)
+  })
+
+  it('can check off an item as completed', () => {
+    // In addition to using the `get` command to get an element by selector,
+    // we can also use the `contains` command to get an element by its contents.
+    // However, this will yield the <label>, which is lowest-level element that contains the text.
+    // In order to check the item, we'll find the <input> element for this <label>
+    // by traversing up the dom to the parent element. From there, we can `find`
+    // the child checkbox <input> element and use the `check` command to check it.
+    cy.contains('Pay electric bill')
+      .parent()
+      .find('input[type=checkbox]')
+      .check()
+
+    // Now that we've checked the button, we can go ahead and make sure
+    // that the list element is now marked as completed.
+    // Again we'll use `contains` to find the <label> element and then use the `parents` command
+    // to traverse multiple levels up the dom until we find the corresponding <li> element.
+    // Once we get that element, we can assert that it has the completed class.
+    cy.contains('Pay electric bill')
+      .parents('li')
+      .should('have.class', 'completed')
+  })
+
+  context('with a checked task', () => {
+    beforeEach(() => {
+      // We'll take the command we used above to check off an element
+      // Since we want to perform multiple tests that start with checking
+      // one element, we put it in the beforeEach hook
+      // so that it runs at the start of every test.
+      cy.contains('Pay electric bill')
+        .parent()
+        .find('input[type=checkbox]')
+        .check()
+    })
+
+    it('can filter for uncompleted tasks', () => {
+      // We'll click on the "active" button in order to
+      // display only incomplete items
+      cy.contains('Active').click()
+
+      // After filtering, we can assert that there is only the one
+      // incomplete item in the list.
+      cy.get('.todo-list li')
+        .should('have.length', 1)
+        .first()
+        .should('have.text', 'Walk the dog')
+
+      // For good measure, let's also assert that the task we checked off
+      // does not exist on the page.
+      cy.contains('Pay electric bill').should('not.exist')
+    })
+
+    it('can filter for completed tasks', () => {
+      // We can perform similar steps as the test above to ensure
+      // that only completed tasks are shown
+      cy.contains('Completed').click()
+
+      cy.get('.todo-list li')
+        .should('have.length', 1)
+        .first()
+        .should('have.text', 'Pay electric bill')
+
+      cy.contains('Walk the dog').should('not.exist')
+    })
+
+    it('can delete all completed tasks', () => {
+      // First, let's click the "Clear completed" button
+      // `contains` is actually serving two purposes here.
+      // First, it's ensuring that the button exists within the dom.
+      // This button only appears when at least one task is checked
+      // so this command is implicitly verifying that it does exist.
+      // Second, it selects the button so we can click it.
+      cy.contains('Clear completed').click()
+
+      // Then we can make sure that there is only one element
+      // in the list and our element does not exist
+      cy.get('.todo-list li')
+        .should('have.length', 1)
+        .should('not.have.text', 'Pay electric bill')
+
+      // Finally, make sure that the clear button no longer exists.
+      cy.contains('Clear completed').should('not.exist')
+    })
+  })
+})