eslint-plugin-cypress 0.0.0-dev.1109

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

@@ -0,0 +1,71 @@
+'use strict'
+
+const { isRootCypress } = require('../utils/is-root-cypress')
+
+// ------------------------------------------------------------------------------
+// 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 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/lib/rules/no-debug.js

@@ -0,0 +1,52 @@
+'use strict'
+
+const { isRootCypress } = require('../utils/is-root-cypress')
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'disallow using `cy.debug()` calls',
+      category: 'Possible Errors',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-debug.md',
+    },
+    fixable: null, // or "code" or "whitespace"
+    schema: [],
+    messages: {
+      unexpected: 'Do not use cy.debug command',
+    },
+  },
+
+  create(context) {
+    // variables should be defined here
+
+    // ----------------------------------------------------------------------
+    // Helpers
+    // ----------------------------------------------------------------------
+    function isCallingDebug(node) {
+      return node.callee
+        && node.callee.property
+        && node.callee.property.type === 'Identifier'
+        && node.callee.property.name === 'debug'
+    }
+
+    // ----------------------------------------------------------------------
+    // Public
+    // ----------------------------------------------------------------------
+
+    return {
+
+      CallExpression(node) {
+        if (isRootCypress(node) && isCallingDebug(node)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+
+    }
+  },
+}

package/lib/rules/no-force.js

@@ -0,0 +1,79 @@
+'use strict'
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'disallow using `force: true` with action commands',
+      category: 'Possible Errors',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-force.md',
+    },
+    fixable: null, // or "code" or "whitespace"
+    schema: [],
+    messages: {
+      unexpected: 'Do not use force on click and type calls',
+    },
+  },
+
+  create(context) {
+    // variables should be defined here
+
+    // ----------------------------------------------------------------------
+    // Helpers
+    // ----------------------------------------------------------------------
+    function isCallingClickOrType(node) {
+      const allowedMethods = ['click', 'dblclick', 'type', 'trigger', 'check', 'rightclick', 'focus', 'select']
+
+      return node.property && node.property.type === 'Identifier'
+        && 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'
+        && node.callee.object.name === 'cy'
+    }
+
+    function hasOptionForce(node) {
+      return node.arguments && node.arguments.length
+        && node.arguments.some((arg) => {
+          return arg.type === 'ObjectExpression' && arg.properties.some((propNode) => propNode.key && propNode.key.name === 'force')
+        })
+    }
+
+    function deepCheck(node, checkFunc) {
+      let currentNode = node
+
+      while (currentNode.parent) {
+        if (checkFunc(currentNode.parent)) {
+          return true
+        }
+
+        currentNode = currentNode.parent
+      }
+
+      return false
+    }
+
+    // ----------------------------------------------------------------------
+    // Public
+    // ----------------------------------------------------------------------
+
+    return {
+
+      CallExpression(node) {
+        if (isCypressCall(node) && deepCheck(node, isCallingClickOrType) && deepCheck(node, hasOptionForce)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+
+    }
+  },
+}

package/lib/rules/no-pause.js

@@ -0,0 +1,52 @@
+'use strict'
+
+const { isRootCypress } = require('../utils/is-root-cypress')
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'disallow using `cy.pause()` calls',
+      category: 'Possible Errors',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-pause.md',
+    },
+    fixable: null, // or "code" or "whitespace"
+    schema: [],
+    messages: {
+      unexpected: 'Do not use cy.pause command',
+    },
+  },
+
+  create(context) {
+    // variables should be defined here
+
+    // ----------------------------------------------------------------------
+    // Helpers
+    // ----------------------------------------------------------------------
+    function isCallingPause(node) {
+      return node.callee
+        && node.callee.property
+        && node.callee.property.type === 'Identifier'
+        && node.callee.property.name === 'pause'
+    }
+
+    // ----------------------------------------------------------------------
+    // Public
+    // ----------------------------------------------------------------------
+
+    return {
+
+      CallExpression(node) {
+        if (isRootCypress(node) && isCallingPause(node)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+
+    }
+  },
+}

package/lib/rules/no-unnecessary-waiting.js

@@ -0,0 +1,95 @@
+'use strict'
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow waiting for arbitrary time periods',
+      category: 'Possible Errors',
+      recommended: true,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-unnecessary-waiting.md',
+    },
+    schema: [],
+    messages: {
+      unexpected: 'Do not wait for arbitrary time periods',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode()
+
+    return {
+      CallExpression(node) {
+        if (isCallingCyWait(node)) {
+          const scope = sourceCode.getScope
+            ? sourceCode.getScope(node)
+            : context.getScope()
+
+          if (isIdentifierNumberConstArgument(node, scope) || isNumberArgument(node)) {
+            context.report({ node, messageId: 'unexpected' })
+          }
+        }
+      },
+    }
+  },
+}
+
+function nodeIsCalledByCy(node) {
+  if (node.type === 'Identifier' && node.name === 'cy') return true
+
+  if (typeof node.callee === 'undefined' || typeof node.callee.object === 'undefined') {
+    return false
+  }
+
+  return nodeIsCalledByCy(node.callee.object)
+}
+
+function isCallingCyWait(node) {
+  return node.callee.type === 'MemberExpression'
+    && nodeIsCalledByCy(node)
+    && node.callee.property.type === 'Identifier'
+    && node.callee.property.name === 'wait'
+}
+
+function isNumberArgument(node) {
+  return node.arguments.length > 0
+    && node.arguments[0].type === 'Literal'
+    && typeof (node.arguments[0].value) === 'number'
+}
+
+function isIdentifierNumberConstArgument(node, scope) {
+  if (node.arguments.length === 0) return false
+
+  if (node.arguments[0].type !== 'Identifier') return false
+
+  const identifier = node.arguments[0]
+  const resolvedIdentifier = scope.references.find((ref) => ref.identifier === identifier).resolved
+  const definition = resolvedIdentifier.defs[0]
+  const isVariable = definition.type === 'Variable'
+
+  // const amount = 1000 or const amount = '@alias'
+  // cy.wait(amount)
+  if (isVariable) {
+    if (!definition.node.init) return false
+
+    return typeof definition.node.init.value === 'number'
+  }
+
+  // import { WAIT } from './constants'
+  // cy.wait(WAIT)
+  // we don't know if WAIT is a number or alias '@someRequest', so don't fail
+  if (definition.type === 'ImportBinding') return false
+
+  // Get the identifier's parent node to check for a default value.
+  // For `function wait (amount = 1) { ... }`, `definition.name` is the `amount` Identifier,
+  // and its parent is the AssignmentPattern `amount = 1`.
+  // This also handles destructured parameters like `function wait ({ ms = 1 }) { ... }`.
+  const nameParent = definition.name.parent
+
+  // function wait (amount) { cy.wait(amount) }
+  // we can't know the type of value, so don't fail
+  if (!nameParent || nameParent.type !== 'AssignmentPattern') return false
+
+  // function wait (amount = 1) { cy.wait(amount) } or
+  // function wait (amount = '@alias') { cy.wait(amount) }
+  return typeof nameParent.right.value === 'number'
+}

package/lib/rules/no-xpath.js

@@ -0,0 +1,43 @@
+'use strict'
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow using `cy.xpath()` calls',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-xpath.md',
+    },
+    fixable: null, // Or `code` or `whitespace`
+    schema: [], // Add a schema if the rule has options
+    messages: {
+      unexpected:
+        'cy.xpath() is deprecated and unsupported. '
+        + 'Consider using cy.get() with appropriate selectors instead.',
+    },
+    deprecated: {
+      message:
+        'The reason for rule deprecation is the underlying deprecation and removal of support for the `@cypress/xpath` npm module in 2023. '
+        + 'The rule is currently provided as a convenience to identify existing code that requires migration to supported API calls '
+        + 'and it is planned for removal in a future major release of the plugin.',
+    },
+  },
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isCallingCyXpath(node)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+    }
+  },
+}
+
+function isCallingCyXpath(node) {
+  return node.callee.type === 'MemberExpression'
+    && node.callee.object.type === 'Identifier'
+    && node.callee.object.name === 'cy'
+    && node.callee.property.type === 'Identifier'
+    && node.callee.property.name === 'xpath'
+}

package/lib/rules/require-data-selectors.js

@@ -0,0 +1,77 @@
+'use strict'
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'require `data-*` attribute selectors',
+      category: 'Possible Errors',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/require-data-selectors.md',
+    },
+    schema: [],
+    messages: {
+      unexpected: 'use data-* attribute selectors instead of classes or tag names',
+    },
+  },
+
+  create(context) {
+    const variablesSet = new Set()
+    return {
+      VariableDeclarator(node) {
+        if (node.init && node.id && node.id.type === 'Identifier') {
+          if (isDataNode(node.init, variablesSet)) {
+            variablesSet.add(node.id.name)
+          }
+        }
+      },
+
+      CallExpression(node) {
+        if (isCallingCyGet(node) && !isDataArgument(node, variablesSet)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+    }
+  },
+}
+
+function isCallingCyGet(node) {
+  return node.callee.type === 'MemberExpression'
+    && node.callee.object.type === 'Identifier'
+    && node.callee.object.name === 'cy'
+    && node.callee.property.type === 'Identifier'
+    && node.callee.property.name === 'get'
+}
+
+function isDataArgument(node, dataVariables) {
+  if (node.arguments.length === 0) return false
+
+  const firstArg = node.arguments[0]
+  return isDataNode(firstArg, dataVariables)
+}
+
+function isDataNode(firstArg, dataVariables) {
+  if (firstArg.type === 'Literal') {
+    return isAliasOrDataSelector(String(firstArg.value))
+  }
+
+  if (firstArg.type === 'TemplateLiteral') {
+    return isAliasOrDataSelector(String(firstArg.quasis[0].value.cooked))
+  }
+
+  if (firstArg.type === 'Identifier') {
+    return dataVariables.has(firstArg.name)
+  }
+
+  if (firstArg.type === 'ConditionalExpression') {
+    return isDataNode(firstArg.consequent, dataVariables)
+      && isDataNode(firstArg.alternate, dataVariables)
+  }
+
+  return false
+}
+
+function isAliasOrDataSelector(selector) {
+  return ['[data-', '@'].some(function (validValue) {
+    return selector.startsWith(validValue)
+  })
+}

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

@@ -0,0 +1,123 @@
+'use strict'
+
+const { basename } = require('path')
+const { isRootCypress } = require('../utils/is-root-cypress')
+
+const NAME = basename(__dirname)
+const DESCRIPTION = 'disallow actions within chains'
+
+/**
+ * Commands listed in the documentation with text: 'It is unsafe to chain further commands that rely on the subject after xxx.'
+ * See {@link https://docs.cypress.io/app/core-concepts/retry-ability#Actions-should-be-at-the-end-of-chains-not-the-middle Actions should be at the end of chains, not the middle}
+ * for more information.
+ *
+ * @type {string[]}
+ */
+const unsafeToChainActions = [
+  'blur',
+  'clear',
+  'click',
+  'check',
+  'dblclick',
+  'each',
+  'focus',
+  'rightclick',
+  'screenshot',
+  'scrollIntoView',
+  'scrollTo',
+  'select',
+  'selectFile',
+  'spread',
+  'submit',
+  'type',
+  'trigger',
+  'uncheck',
+  'within',
+]
+
+/**
+ * @type {import('eslint').Rule.RuleMetaData['schema']}
+ */
+const schema = {
+  title: NAME,
+  description: DESCRIPTION,
+  type: 'object',
+  properties: {
+    methods: {
+      type: 'array',
+      description:
+        'An additional list of methods to check for unsafe chaining.',
+      default: [],
+    },
+  },
+  additionalProperties: false,
+}
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @returns {Record<string, any>}
+ */
+const getDefaultOptions = (context) => {
+  return Object.entries(schema.properties).reduce((acc, [key, value]) => {
+    if (!(value.default in value)) return acc
+
+    return {
+      ...acc,
+      [key]: value.default,
+    }
+  }, context.options[0] || {})
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: DESCRIPTION,
+      category: 'Possible Errors',
+      recommended: true,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/unsafe-to-chain-command.md',
+    },
+    schema: [schema],
+    messages: {
+      unexpected:
+        'It is unsafe to chain further commands that rely on the subject after this command. It is best to split the chain, chaining again from `cy.` in a next command line.',
+    },
+  },
+  create(context) {
+    const { methods } = getDefaultOptions(context)
+
+    return {
+      CallExpression(node) {
+        if (
+          isRootCypress(node, context)
+          && isActionUnsafeToChain(node, methods)
+          && node.parent.type === 'MemberExpression'
+        ) {
+          context.report({
+            node,
+            messageId: 'unexpected',
+          })
+        }
+      },
+    }
+  },
+}
+
+/**
+ * @param {import('estree').Node} node
+ * @param {(string | RegExp)[]} additionalMethods
+ */
+const isActionUnsafeToChain = (node, additionalMethods = []) => {
+  const unsafeActionsRegex = new RegExp([
+    ...unsafeToChainActions.map((action) => `^${action}$`),
+    ...additionalMethods.map((method) => method instanceof RegExp ? method.source : method),
+  ].join('|'))
+
+  return (
+    node.callee
+    && node.callee.property
+    && node.callee.property.type === 'Identifier'
+    && unsafeActionsRegex.test(node.callee.property.name)
+  )
+}

package/lib/utils/is-root-cypress.js

@@ -0,0 +1,46 @@
+'use strict'
+
+/**
+ * Whether `node` is a CallExpression that belongs to a Cypress command chain
+ * rooted at `cy` (walks `callee.object` through nested calls).
+ * If type information are available, additionally checks the return type of helper functions.
+ *
+ * @param {import('estree').Node} node
+ * @returns {boolean}
+ */
+const isRootCypress = (node, context) => {
+  if (node.type !== 'CallExpression') {
+    return false
+  }
+
+  const calleeType = node.callee.type
+  if (calleeType === 'MemberExpression') {
+    if (node.callee.object.type === 'Identifier' && node.callee.object.name === 'cy') {
+      return true
+    }
+
+    return isRootCypress(node.callee.object, context)
+  }
+
+  if (calleeType === 'Identifier') {
+    const services = context?.sourceCode?.parserServices
+    if (services?.program && services.esTreeNodeToTSNodeMap) {
+      const checker = services.program.getTypeChecker()
+      const tsNode = services.esTreeNodeToTSNodeMap.get(node)
+      if (tsNode) {
+        const signature = checker.getResolvedSignature(tsNode)
+        if (signature) {
+          const returnType = checker.getReturnTypeOfSignature(signature)
+          const symbol = returnType.getSymbol()
+          if (symbol) {
+            return checker.getFullyQualifiedName(symbol) === 'Cypress.Chainable'
+          }
+        }
+      }
+    }
+  }
+
+  return false
+}
+
+module.exports = { isRootCypress }