eslint-plugin-cypress 0.0.0-dev.1109

package/docs/rules/no-force.md

@@ -0,0 +1,51 @@
+# cypress/no-force
+
+📝 Disallow using `force: true` with action commands.
+
+<!-- end auto-generated rule header -->
+
+Using `force: true` on inputs appears to be confusing rather than helpful.
+It usually silences the actual problem instead of providing a way to overcome it.
+See [Cypress Core Concepts](https://docs.cypress.io/app/core-concepts/interacting-with-elements.html#Forcing).
+
+If enabling this rule, it's recommended to set the severity to `warn`.
+
+## Rule Details
+
+This rule disallows using the `force` option on:[`.click()`](https://on.cypress.io/click),
+[`.dblclick()`](https://on.cypress.io/dblclick), [`.type()`](https://on.cypress.io/type),
+[`.rightclick()`](https://on.cypress.io/rightclick), [`.select()`](https://on.cypress.io/select),
+[`.focus()`](https://on.cypress.io/focus), [`.check()`](https://on.cypress.io/check),
+and [`.trigger()`](https://on.cypress.io/trigger).
+
+Examples of **incorrect** code for this rule:
+
+```js
+cy.get('button').click({ force: true })
+cy.get('button').dblclick({ force: true })
+cy.get('input').type('somth', { force: true })
+cy.get('div').find('.foo').find('.bar').trigger('change', { force: true })
+cy.get('input').trigger('click', { force: true })
+cy.get('input').rightclick({ force: true })
+cy.get('input').check({ force: true })
+cy.get('input').select({ force: true })
+cy.get('input').focus({ force: true })
+```
+
+Examples of **correct** code for this rule:
+
+```js
+cy.get('button').click()
+cy.get('button').click({ multiple: true })
+cy.get('button').dblclick()
+cy.get('input').type('somth')
+cy.get('input').trigger('click', { anyoption: true })
+cy.get('input').rightclick({ anyoption: true })
+cy.get('input').check()
+cy.get('input').select()
+cy.get('input').focus()
+```
+
+## When Not To Use It
+
+If you don't mind using `{ force: true }` with action commands, then turn this rule off.

package/docs/rules/no-pause.md

@@ -0,0 +1,22 @@
+# cypress/no-pause
+
+📝 Disallow using `cy.pause()` calls.
+
+<!-- end auto-generated rule header -->
+
+It is recommended to remove any [cy.pause](https://on.cypress.io/pause) commands before committing specs to avoid other developers getting unexpected results.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```js
+cy.pause()
+cy.get('selector').pause()
+```
+
+Examples of **correct** code for this rule:
+
+```js
+cy.get('selector')
+```

package/docs/rules/no-unnecessary-waiting.md

@@ -0,0 +1,11 @@
+# cypress/no-unnecessary-waiting
+
+📝 Disallow waiting for arbitrary time periods.
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+## Further Reading
+
+See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Unnecessary-Waiting).

package/docs/rules/no-xpath.md

@@ -0,0 +1,34 @@
+# cypress/no-xpath
+
+📝 Disallow using `cy.xpath()` calls.
+
+❌ This rule is deprecated. 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.
+
+<!-- end auto-generated rule header -->
+
+This rule disallows the usage of `cy.xpath()` for selecting elements.
+
+## Rule Details
+
+Examples of **incorrect** code for this rule:
+
+```js
+cy.xpath('//div[@class=\"container\"]').click()
+```
+
+Examples of **correct** code for this rule:
+
+```js
+cy.get('[data-cy="container"]').click()
+```
+
+## Migration
+
+Both [@cypress/xpath](https://www.npmjs.com/package/@cypress/xpath) and the earlier [cypress-xpath](https://www.npmjs.com/package/cypress-xpath) npm packages are deprecated and no longer supported.
+These packages previously provided the command `cy.xpath()` and they should be uninstalled from the Cypress project after migrating `cy.xpath()` selection to `cy.get()`. See below for more details.
+
+After migrating away from `cy.xpath()`, the rule can be set to `off` or can be permanently removed from the ESLint configuration.
+
+## Further Reading
+
+See [the Cypress Best Practices guide](https://docs.cypress.io/app/core-concepts/best-practices.html#Selecting-Elements).

package/docs/rules/require-data-selectors.md

@@ -0,0 +1,59 @@
+# cypress/require-data-selectors
+
+📝 Require `data-*` attribute selectors.
+
+<!-- end auto-generated rule header -->
+
+Require `cy.get` to use only selectors that target `data-*` attributes.
+
+> Note: If you use this rule, consider only using the `warn` error level, since using `data-*` attribute selectors may not always be possible.
+
+## Rule Details
+
+This rule checks the first parameter of each `cy.get`. It supports template literals, variable (re-)assignments and conditional expressions. For conditionals, all branches must conform to this rule.
+
+Cypress aliases (as defined by `cy.as`) are always allowed.
+
+Examples of **incorrect** code for this rule:
+
+```js
+cy.get('.a')
+cy.get('[daedta-cy=submit]').click()
+cy.get('[d-cy=submit]')
+cy.get('.btn-large').click()
+cy.get('.btn-.large').click()
+cy.get(condition ? '[data-cy=submit]' : '.btn-large')
+
+const CLASS_SELECTOR = '.my-class'
+cy.get(CLASS_SELECTOR)
+
+const TYPE = 'submit'
+const SUBMIT_TEMPLATE = `.${TYPE}`
+cy.get(SUBMIT_TEMPLATE)
+
+const MY_SUBMIT_TEMPLATE = SUBMIT_TEMPLATE
+cy.get(MY_SUBMIT_TEMPLATE)
+```
+
+Examples of **correct** code for this rule:
+
+```js
+cy.get('[data-cy=submit]').click()
+cy.get('[data-QA=submit]')
+cy.get(`[data-QA=submit]`)
+cy.get(condition ? '[data-cy=submit]' : '[data-QA=submit]')
+
+const ASSESSMENT_SUBMIT = '[data-cy=assessment-submit]'
+cy.get(ASSESSMENT_SUBMIT).click()
+
+const TYPE = 'submit'
+const SUBMIT_TEMPLATE = `[data-QA=${TYPE}]`
+cy.get(SUBMIT_TEMPLATE)
+
+const MY_SUBMIT_TEMPLATE = SUBMIT_TEMPLATE
+cy.get(MY_SUBMIT_TEMPLATE)
+```
+
+## Further Reading
+
+See [the Cypress Best Practices guide](https://docs.cypress.io/app/core-concepts/best-practices.html#Selecting-Elements).

package/docs/rules/unsafe-to-chain-command.md

@@ -0,0 +1,33 @@
+# cypress/unsafe-to-chain-command
+
+📝 Disallow actions within chains.
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+### Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name      | Description                                                 | Type  | Default |
+| :-------- | :---------------------------------------------------------- | :---- | :------ |
+| `methods` | An additional list of methods to check for unsafe chaining. | Array | `[]`    |
+
+<!-- end auto-generated rule options list -->
+
+## Typed Linting
+
+If [Typed Linting](../../README.md#typed-linting) is enabled, this rule also catches unsafe chaining even when the Cypress chain was started from a helper function.
+
+```js
+function getTodo() {
+  return cy.get('.todo')
+}
+
+getTodo().type('todo A{enter}').type('todo B{enter}')
+```
+
+## Further Reading
+
+See [retry-ability guide](https://docs.cypress.io/app/core-concepts/retry-ability#Actions-should-be-at-the-end-of-chains-not-the-middle).

package/lib/config/recommended.js

@@ -0,0 +1,14 @@
+'use strict'
+
+module.exports = {
+  plugins: ['cypress'],
+  env: {
+    'cypress/globals': true,
+  },
+  rules: {
+    'cypress/no-assigning-return-values': 'error',
+    'cypress/no-unnecessary-waiting': 'error',
+    'cypress/no-async-tests': 'error',
+    'cypress/unsafe-to-chain-command': 'error',
+  },
+}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+import type { ESLint, Linter } from 'eslint'
+
+declare const plugin: {
+  meta: { name: string, version: string }
+  configs: {
+    globals: Linter.Config<Linter.RulesRecord>
+    recommended: Linter.Config<Linter.RulesRecord>
+  }
+  rules: NonNullable<ESLint.Plugin['rules']>
+}
+
+export = plugin

package/lib/index.js

@@ -0,0 +1,65 @@
+const globals = require('globals')
+const { name, version } = require('../package.json')
+
+const plugin = {
+  meta: { name, version },
+  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'),
+    'no-chained-get': require('./rules/no-chained-get'),
+    'no-debug': require('./rules/no-debug'),
+    'no-force': require('./rules/no-force'),
+    'no-pause': require('./rules/no-pause'),
+    'no-unnecessary-waiting': require('./rules/no-unnecessary-waiting'),
+    'no-xpath': require('./rules/no-xpath'),
+    'require-data-selectors': require('./rules/require-data-selectors'),
+    'unsafe-to-chain-command': require('./rules/unsafe-to-chain-command'),
+  },
+}
+
+const commonGlobals
+  = Object.assign({
+    cy: false,
+    Cypress: false,
+    expect: false,
+    assert: false,
+    chai: false,
+  }, globals.browser, globals.mocha)
+
+Object.assign(plugin.configs, {
+  globals: {
+    name: 'cypress/globals',
+    plugins: {
+      cypress: plugin,
+    },
+    languageOptions: {
+      globals:
+        commonGlobals,
+    },
+  },
+})
+
+Object.assign(plugin.configs, {
+  recommended: {
+    name: 'cypress/recommended',
+    plugins: {
+      cypress: plugin,
+    },
+    rules: {
+      'cypress/no-assigning-return-values': 'error',
+      'cypress/no-unnecessary-waiting': 'error',
+      'cypress/no-async-tests': 'error',
+      'cypress/unsafe-to-chain-command': 'error',
+    },
+    languageOptions: {
+      globals:
+        commonGlobals,
+    },
+  },
+})
+
+module.exports = plugin

package/lib/rules/assertion-before-screenshot.js

@@ -0,0 +1,99 @@
+'use strict'
+
+const { isRootCypress } = require('../utils/is-root-cypress')
+
+const assertionCommands = [
+  // assertions
+  'should',
+  'and',
+  'contains',
+
+  // retries until it gets something
+  'get',
+
+  // not an assertion, but unlikely to require waiting for render
+  'scrollIntoView',
+  'scrollTo',
+]
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'require screenshots to be preceded by an assertion',
+      category: 'Possible Errors',
+      recommended: false,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/assertion-before-screenshot.md',
+    },
+    schema: [],
+    messages: {
+      unexpected: 'Make an assertion on the page state before taking a screenshot',
+    },
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isCallingCyScreenshot(node) && !isPreviousAnAssertion(node)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+    }
+  },
+}
+
+function getPreviousInChain(node) {
+  return node.type === 'CallExpression'
+    && node.callee.type === 'MemberExpression'
+    && node.callee.object.type === 'CallExpression'
+    && node.callee.object.callee.type === 'MemberExpression'
+    && node.callee.object.callee.property.type === 'Identifier'
+    && node.callee.object.callee.property.name
+}
+
+function getCallExpressionCypressCommand(node) {
+  return isRootCypress(node)
+    && node.callee.property.type === 'Identifier'
+    && node.callee.property.name
+}
+
+function isCallingCyScreenshot(node) {
+  return getCallExpressionCypressCommand(node) === 'screenshot'
+}
+
+function getPreviousCypressCommand(node) {
+  const previousInChain = getPreviousInChain(node)
+
+  if (previousInChain) {
+    return previousInChain
+  }
+
+  while (node.parent && !node.parent.body) {
+    node = node.parent
+  }
+
+  if (!node.parent || !node.parent.body) return null
+
+  const body = node.parent.body.type === 'BlockStatement' ? node.parent.body.body : node.parent.body
+
+  const index = body.indexOf(node)
+
+  // in the case of a function declaration it won't be found
+  if (index < 0) return null
+
+  if (index === 0) return getPreviousCypressCommand(node.parent)
+
+  const previousStatement = body[index - 1]
+
+  if (previousStatement.type !== 'ExpressionStatement'
+    || previousStatement.expression.type !== 'CallExpression') {
+    return null
+  }
+
+  return getCallExpressionCypressCommand(previousStatement.expression)
+}
+
+function isPreviousAnAssertion(node) {
+  const previousCypressCommand = getPreviousCypressCommand(node)
+
+  return assertionCommands.indexOf(previousCypressCommand) >= 0
+}

package/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')
+            },
+          })
+        }
+      },
+    }
+  },
+}

package/lib/rules/no-assigning-return-values.js

@@ -0,0 +1,68 @@
+'use strict'
+
+// safely get nested object property
+function get(obj, propertyString = '') {
+  const properties = propertyString.split('.')
+
+  for (let i = 0; i < properties.length; i++) {
+    const value = (obj || {})[properties[i]]
+
+    if (value == null) return value
+
+    obj = value
+  }
+
+  return obj
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow assigning return values of `cy` calls',
+      category: 'Possible Errors',
+      recommended: true,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-assigning-return-values.md',
+    },
+    schema: [],
+    messages: {
+      unexpected: 'Do not assign the return value of a Cypress command',
+    },
+  },
+  create(context) {
+    return {
+      VariableDeclaration(node) {
+        if (node.declarations.some(isCypressCommandDeclaration)) {
+          context.report({ node, messageId: 'unexpected' })
+        }
+      },
+    }
+  },
+}
+
+const allowedCommands = {
+  now: true,
+  spy: true,
+  state: true,
+  stub: true,
+}
+
+function isCypressCommandDeclaration(declarator) {
+  let object = get(declarator, 'init.callee.object')
+
+  if (!object) return
+
+  while (object.callee) {
+    object = object.callee.object
+
+    if (!object) return
+  }
+
+  const commandName = get(declarator, 'init.callee.property.name')
+
+  const parent = get(object, 'parent.property.name') || get(declarator, 'id.name')
+
+  if (commandName && (allowedCommands[commandName] || allowedCommands[parent])) return
+
+  return object.name === 'cy'
+}

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

@@ -0,0 +1,53 @@
+'use strict'
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow using `async`/`await` in Cypress `before` methods',
+      category: 'Possible Errors',
+      recommended: true,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-async-before.md',
+    },
+    schema: [],
+    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
+    }
+    const sourceCode = context.sourceCode ?? context.getSourceCode()
+
+    return {
+      Identifier(node) {
+        if (node.name === 'cy' || node.name === 'Cypress') {
+          const ancestors = sourceCode.getAncestors
+            ? sourceCode.getAncestors(node)
+            : 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/lib/rules/no-async-tests.js

@@ -0,0 +1,53 @@
+'use strict'
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow using `async`/`await` in Cypress test cases',
+      category: 'Possible Errors',
+      recommended: true,
+      url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-async-tests.md',
+    },
+    schema: [],
+    messages: {
+      unexpected: 'Avoid using async functions with Cypress tests',
+    },
+  },
+
+  create(context) {
+    function isTestBlock(callExpressionNode) {
+      const { type, name } = callExpressionNode.callee
+
+      return type === 'Identifier'
+        && (name === 'it' || name === 'test')
+    }
+
+    function isTestAsync(node) {
+      return node.arguments
+        && node.arguments.length >= 2
+        && node.arguments[1].async === true
+    }
+    const sourceCode = context.sourceCode ?? context.getSourceCode()
+
+    return {
+      Identifier(node) {
+        if (node.name === 'cy' || node.name === 'Cypress') {
+          const ancestors = sourceCode.getAncestors
+            ? sourceCode.getAncestors(node)
+            : context.getAncestors()
+          const asyncTestBlocks = ancestors
+            .filter((n) => n.type === 'CallExpression')
+            .filter(isTestBlock)
+            .filter(isTestAsync)
+
+          if (asyncTestBlocks.length >= 1) {
+            asyncTestBlocks.forEach((node) => {
+              context.report({ node, messageId: 'unexpected' })
+            })
+          }
+        }
+      },
+    }
+  },
+}