feat: added no-and rule to ensure .and() follows certain commands (#310)

Author: todd-m-kemp

docs/rules/no-and.md

@@ -0,0 +1,34 @@
+# cypress/no-and
+
+📝 Enforce `.should()` over `.and()` for starting assertion chains.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+Cypress's [.and()](https://on.cypress.io/and) is an alias for [.should()](https://on.cypress.io/should). Using `.and()` reads naturally when it follows `.should()` or `.contains()` — it continues an assertion chain like "should be empty **and** be hidden." In other positions, `.should()` is clearer.
+
+## Rule Details
+
+This rule allows `.and()` only when it immediately follows `.should()`, `.and()`, or `.contains()`. In all other positions, it flags `.and()` and auto-fixes it to `.should()`.
+
+Examples of **incorrect** code for this rule:
+
+```js
+cy.get('elem').and('have.text', 'blah')
+cy.get('foo').find('.bar').and('have.class', 'active')
+cy.get('foo').click().and('be.disabled')
+```
+
+Examples of **correct** code for this rule:
+
+```js
+cy.get('elem').should('have.text', 'blah')
+cy.get('.err').should('be.empty').and('be.hidden')
+cy.contains('Login').and('be.visible')
+cy.get('foo').should('be.visible').and('have.text', 'bar').and('have.class', 'active')
+```
+
+## When Not To Use It
+
+If you prefer using `.and()` interchangeably with `.should()` in all positions, turn this rule off.

lib/index.js

@@ -6,6 +6,7 @@ const plugin = {
   configs: {},
   rules: {
     'assertion-before-screenshot': require('./rules/assertion-before-screenshot'),
+    'no-and': require('./rules/no-and'),
     'no-assigning-return-values': require('./rules/no-assigning-return-values'),
     'no-async-before': require('./rules/no-async-before'),
     'no-async-tests': require('./rules/no-async-tests'),

lib/rules/assertion-before-screenshot.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { isRootCypress } = require('../utils/is-root-cypress')
+
 const assertionCommands = [
   // assertions
   'should',
@@ -39,21 +41,6 @@ module.exports = {
   },
 }
 
-function isRootCypress(node) {
-  while (node.type === 'CallExpression') {
-    if (node.callee.type !== 'MemberExpression') return false
-
-    if (node.callee.object.type === 'Identifier'
-      && node.callee.object.name === 'cy') {
-      return true
-    }
-
-    node = node.callee.object
-  }
-
-  return false
-}
-
 function getPreviousInChain(node) {
   return node.type === 'CallExpression'
     && node.callee.type === 'MemberExpression'

lib/rules/no-and.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const { isRootCypress } = require('../utils/is-root-cypress')
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'enforce .should() over .and() for starting assertion chains',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-and.md',
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      unexpected:
+        'Use .should() here; .and() is only allowed after .should(), .and(), or .contains().',
+    },
+  },
+
+  create(context) {
+    const allowAndAfter = new Set(['should', 'and', 'contains'])
+
+    function isAllowedAfter(node) {
+      const object = node.callee.object
+      if (
+        object
+        && object.type === 'CallExpression'
+        && object.callee.type === 'MemberExpression'
+      ) {
+        return allowAndAfter.has(object.callee.property.name)
+      }
+      return false
+    }
+
+    return {
+      CallExpression(node) {
+        if (
+          node.callee.type === 'MemberExpression'
+          && node.callee.property.name === 'and'
+          && isRootCypress(node)
+          && !isAllowedAfter(node)
+        ) {
+          context.report({
+            node,
+            messageId: 'unexpected',
+            fix(fixer) {
+              return fixer.replaceText(node.callee.property, 'should')
+            },
+          })
+        }
+      },
+    }
+  },
+}

lib/rules/no-chained-get.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { isRootCypress } = require('../utils/is-root-cypress')
+
 // ------------------------------------------------------------------------------
 // Rule Definition
 // ------------------------------------------------------------------------------
@@ -21,24 +23,6 @@ module.exports = {
   },
 
   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

lib/rules/no-debug.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { isRootCypress } = require('../utils/is-root-cypress')
+
 // ------------------------------------------------------------------------------
 // Rule Definition
 // ------------------------------------------------------------------------------
@@ -33,24 +35,14 @@ module.exports = {
         && node.callee.property.name === 'debug'
     }
 
-    function isCypressCall(node) {
-      if (!node.callee || node.callee.type !== 'MemberExpression') {
-        return false
-      }
-      if (node.callee.object.type === 'Identifier' && node.callee.object.name === 'cy') {
-        return true
-      }
-      return isCypressCall(node.callee.object)
-    }
-
     // ----------------------------------------------------------------------
     // Public
     // ----------------------------------------------------------------------
 
     return {
 
       CallExpression(node) {
-        if (isCypressCall(node) && isCallingDebug(node)) {
+        if (isRootCypress(node) && isCallingDebug(node)) {
           context.report({ node, messageId: 'unexpected' })
         }
       },

lib/rules/no-force.js

@@ -33,6 +33,8 @@ module.exports = {
         && allowedMethods.includes(node.property.name)
     }
 
+    // Only the segment whose callee.object is `cy` (not full chain root):
+    // deepCheck walks parents from that node to find `.click()` / `{ force }`.
     function isCypressCall(node) {
       return node.callee.type === 'MemberExpression'
         && node.callee.object.type === 'Identifier'

lib/rules/no-pause.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { isRootCypress } = require('../utils/is-root-cypress')
+
 // ------------------------------------------------------------------------------
 // Rule Definition
 // ------------------------------------------------------------------------------
@@ -33,24 +35,14 @@ module.exports = {
         && node.callee.property.name === 'pause'
     }
 
-    function isCypressCall(node) {
-      if (!node.callee || node.callee.type !== 'MemberExpression') {
-        return false
-      }
-      if (node.callee.object.type === 'Identifier' && node.callee.object.name === 'cy') {
-        return true
-      }
-      return isCypressCall(node.callee.object)
-    }
-
     // ----------------------------------------------------------------------
     // Public
     // ----------------------------------------------------------------------
 
     return {
 
       CallExpression(node) {
-        if (isCypressCall(node) && isCallingPause(node)) {
+        if (isRootCypress(node) && isCallingPause(node)) {
           context.report({ node, messageId: 'unexpected' })
         }
       },

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

@@ -1,6 +1,7 @@
 'use strict'
 
 const { basename } = require('path')
+const { isRootCypress } = require('../utils/is-root-cypress')
 
 const NAME = basename(__dirname)
 const DESCRIPTION = 'disallow actions within chains'
@@ -103,28 +104,6 @@ module.exports = {
   },
 }
 
-/**
- * @param {import('estree').Node} node
- * @returns {boolean}
- */
-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)
-}
-
 /**
  * @param {import('estree').Node} node
  * @param {(string | RegExp)[]} additionalMethods

lib/utils/is-root-cypress.js

@@ -0,0 +1,28 @@
+'use strict'
+
+/**
+ * Whether `node` is a CallExpression that belongs to a Cypress command chain
+ * rooted at `cy` (walks `callee.object` through nested calls).
+ *
+ * @param {import('estree').Node} node
+ * @returns {boolean}
+ */
+function 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)
+}
+
+module.exports = { isRootCypress }