eslint-plugin-cypress 2.10.3 → 2.11.3

package/README.md

@@ -9,6 +9,10 @@ Note: If you installed ESLint globally then you must also install `eslint-plugin
 ```sh
 npm install eslint-plugin-cypress --save-dev
 ```
+or
+```sh
+yarn add eslint-plugin-cypress --dev
+```
 
 ## Usage
 
@@ -30,12 +34,13 @@ You can add rules:
     "cypress/no-assigning-return-values": "error",
     "cypress/no-unnecessary-waiting": "error",
     "cypress/assertion-before-screenshot": "warn",
-    "cypress/no-force": "warn"
+    "cypress/no-force": "warn",
+    "cypress/no-async-tests": "error"
   }
 }
 ```
 
-You can whitelist globals provided by Cypress:
+You can allow certain globals provided by Cypress:
 
 ```json
 {
@@ -57,6 +62,51 @@ Use the recommended configuration and you can forego configuring _plugins_, _rul
 }
 ```
 
+## Disable rules
+
+You can disable specific rules per file, for a portion of a file, or for a single line.
+
+Disable the `cypress/no-unnecessary-waiting` rule for the entire file by placing this at the start of the file:
+
+```js
+/* eslint-disable cypress/no-unnecessary-waiting */
+```
+
+Disable the `cypress/no-unnecessary-waiting` rule for a portion of the file:
+
+```js
+it('waits for a second', () => {
+  ...
+  /* eslint-disable cypress/no-unnecessary-waiting */
+  cy.wait(1000)
+  /* eslint-enable cypress/no-unnecessary-waiting */
+  ...
+})
+```
+
+Disable the `cypress/no-unnecessary-waiting` rule for a specific line:
+
+```js
+it('waits for a second', () => {
+  ...
+  cy.wait(1000) // eslint-disable-line cypress/no-unnecessary-waiting
+  ...
+})
+```
+
+You can also disable a rule for the next line:
+
+```js
+it('waits for a second', () => {
+  ...
+  // eslint-disable-next-line cypress/no-unnecessary-waiting
+  cy.wait(1000)
+  ...
+})
+```
+
+For more, see the [ESLint rules](https://eslint.org/docs/user-guide/configuring/rules) documentation.
+
 ## Rules
 
 These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
@@ -69,7 +119,8 @@ Rules with a check mark (✅) are enabled by default while using the `plugin:cyp
 | :-- | :------------------------------------------------------------------------- | :-------------------------------------------------------------- |
 | ✅  | [no-assigning-return-values](./docs/rules/no-assigning-return-values.md)   | Prevent assigning return values of cy calls                     |
 | ✅  | [no-unnecessary-waiting](./docs/rules/no-unnecessary-waiting.md)           | Prevent waiting for arbitrary time periods                      |
-|     | [no-force](./docs/rules/no-force.md)                                       | Disallow using `force: true` with action commands                  |
+| ✅  | [no-async-tests](./docs/rules/no-async-tests.md)                           | Prevent using async/await in Cypress test case                  |
+|     | [no-force](./docs/rules/no-force.md)                                       | Disallow using `force: true` with action commands               |
 |     | [assertion-before-screenshot](./docs/rules/assertion-before-screenshot.md) | Ensure screenshots are preceded by an assertion                 |
 |     | [require-data-selectors](./docs/rules/require-data-selectors.md)           | Only allow data-\* attribute selectors (require-data-selectors) |
 

package/circle.yml

@@ -1,13 +1,26 @@
-version: 2
+version: 2.1
 
 workflows:
-  version: 2
-  tests:
+  version: 2.1
+  main:
     jobs:
-      - test
+      - lint
+      - test-v4
+      - test-v5
+      - test-v6
+      - release:
+          requires:
+            - lint
+            - test-v4
+            - test-v5
+            - test-v6
+          filters:
+            branches:
+              only:
+                - master
 
 jobs:
-  test:
+  lint:
     docker:
       - image: circleci/node:8
     steps:
@@ -18,9 +31,51 @@ jobs:
       - run:
           name: Lint code
           command: npm run lint
+
+  test-v4:
+    docker:
+      - image: circleci/node:8
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: npm install
+      - run:
+          name: Test ESLint 4
+          command: npm run test:v4
+
+  test-v5:
+    docker:
+      - image: circleci/node:8
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: npm install
       - run:
-          name: Run tests
-          command: npm test
+          name: Test ESLint 5
+          command: npm run test
+
+  test-v6:
+    docker:
+      - image: circleci/node:8
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: npm install
+      - run:
+          name: Test ESLint 6
+          command: npm run test:v6
+
+  release:
+    docker:
+      - image: circleci/node:8
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: npm install
       - run:
-          name: Semantic release
-          command: npm run semantic-release || true
+          name: Run semantic release
+          command: npm run semantic-release

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

@@ -0,0 +1,52 @@
+# Prevent using async/await in Cypress test cases (no-async-tests)
+
+Cypress tests [that return a promise will error](https://docs.cypress.io/guides/references/error-messages.html#Cypress-detected-that-you-returned-a-promise-from-a-command-while-also-invoking-one-or-more-cy-commands-in-that-promise) and cannot run successfully. An `async` function returns a promise under the hood, so a test using an `async` function will also error.
+
+## Rule Details
+
+This rule disallows using `async` test functions.
+
+Examples of **incorrect** code for this rule:
+
+```js
+describe('my feature', () => {
+  it('my test case', async ()  => {
+    await cy.get('.myClass')
+    // other operations
+  })
+})
+```
+
+```js
+describe('my feature', () => {
+  it('my test case', async ()  => {
+    cy
+    .get('.myClass')
+    .click()
+
+    await someAsyncFunction()
+  })
+})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+describe('my feature', () => {
+  it('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 test cases 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/index.js

@@ -4,6 +4,7 @@ module.exports = {
   rules: {
     'no-assigning-return-values': require('./lib/rules/no-assigning-return-values'),
     'no-unnecessary-waiting': require('./lib/rules/no-unnecessary-waiting'),
+    'no-async-tests': require('./lib/rules/no-async-tests'),
     'assertion-before-screenshot': require('./lib/rules/assertion-before-screenshot'),
     'require-data-selectors': require('./lib/rules/require-data-selectors'),
     'no-force': require('./lib/rules/no-force'),

package/jest.config.js

@@ -0,0 +1,6 @@
+const { defaults } = require('jest-config')
+
+module.exports = {
+  testMatch: ['**/tests/**/*.[jt]s?(x)'],
+  testPathIgnorePatterns: [...defaults.testPathIgnorePatterns, '.history'],
+}

package/lib/config/recommended.js

@@ -8,5 +8,6 @@ module.exports = {
   rules: {
     'cypress/no-assigning-return-values': 'error',
     'cypress/no-unnecessary-waiting': 'error',
+    'cypress/no-async-tests': 'error',
   },
 }

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

@@ -1,8 +1,3 @@
-/**
- * @fileoverview Assert on the page state before taking a screenshot, so the screenshot is consistent
- * @author Luke Page
- */
-
 'use strict'
 
 const assertionCommands = [
@@ -17,7 +12,7 @@ const assertionCommands = [
   // not an assertion, but unlikely to require waiting for render
   'scrollIntoView',
   'scrollTo',
-];
+]
 
 module.exports = {
   meta: {
@@ -42,19 +37,22 @@ module.exports = {
   },
 }
 
-function isRootCypress(node) {
-  while(node.type === 'CallExpression') {
+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) {
+function getPreviousInChain (node) {
   return node.type === 'CallExpression' &&
          node.callee.type === 'MemberExpression' &&
          node.callee.object.type === 'CallExpression' &&
@@ -63,7 +61,7 @@ function getPreviousInChain(node) {
          node.callee.object.callee.property.name
 }
 
-function getCallExpressionCypressCommand(node) {
+function getCallExpressionCypressCommand (node) {
   return isRootCypress(node) &&
          node.callee.property.type === 'Identifier' &&
          node.callee.property.name
@@ -73,14 +71,14 @@ function isCallingCyScreenshot (node) {
   return getCallExpressionCypressCommand(node) === 'screenshot'
 }
 
-function getPreviousCypressCommand(node) {
+function getPreviousCypressCommand (node) {
   const previousInChain = getPreviousInChain(node)
 
   if (previousInChain) {
     return previousInChain
   }
 
-  while(node.parent && !node.parent.body) {
+  while (node.parent && !node.parent.body) {
     node = node.parent
   }
 
@@ -93,18 +91,20 @@ function getPreviousCypressCommand(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);
+  if (index === 0) return getPreviousCypressCommand(node.parent)
 
   const previousStatement = body[index - 1]
 
   if (previousStatement.type !== 'ExpressionStatement' ||
-      previousStatement.expression.type !== 'CallExpression')
+      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-assigning-return-values.js

@@ -1,18 +1,17 @@
-/**
- * @fileoverview Prevent assigning return value of cy calls
- * @author Elad Shahar
- */
-
 '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
 }
 
@@ -40,7 +39,7 @@ module.exports = {
   },
 }
 
-const whitelistedCommands = {
+const allowedCommands = {
   now: true,
   spy: true,
   state: true,
@@ -57,9 +56,12 @@ function isCypressCommandDeclaration (declarator) {
 
     if (!object) return
   }
+
   const commandName = get(declarator, 'init.callee.property.name')
 
-  if (commandName && whitelistedCommands[commandName]) return
+  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-tests.js

@@ -0,0 +1,47 @@
+'use strict'
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Prevent using async/await in Cypress test cases',
+      category: 'Possible Errors',
+      recommended: true,
+    },
+    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
+    }
+
+    return {
+      Identifier (node) {
+        if (node.name === 'cy' || node.name === 'Cypress') {
+          const ancestors = 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' })
+            })
+          }
+        }
+      },
+    }
+  },
+}

package/lib/rules/no-force.js

@@ -1,8 +1,3 @@
-/**
- * @fileoverview Disallow using of \'force: true\' option for click and type calls
- * @author Alex Kuznetsov
- */
-
 'use strict'
 
 //------------------------------------------------------------------------------
@@ -47,7 +42,7 @@ module.exports = {
 
       return node.arguments && node.arguments.length &&
       node.arguments.some((arg) => {
-        return arg.type === 'ObjectExpression' && arg.properties.some((propNode) => propNode.key.name === 'force')
+        return arg.type === 'ObjectExpression' && arg.properties.some((propNode) => propNode.key && propNode.key.name === 'force')
       })
     }
 

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

@@ -1,8 +1,3 @@
-/**
- * @fileoverview Prevent waiting for arbitrary time periods
- * @author Elad Shahar
- */
-
 'use strict'
 
 module.exports = {
@@ -61,7 +56,8 @@ function isIdentifierNumberConstArgument (node, scope) {
 
   if (node.arguments[0].type !== 'Identifier') return false
 
-  const resolvedIdentifier = scope.resolve(node.arguments[0]).resolved
+  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'
 

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

@@ -1,7 +1,3 @@
-/**
- * @fileoverview Use data-* attribute selectors instead of classes or tag names
- * @author Sandeep Baldawa
- */
 'use strict'
 
 module.exports = {
@@ -40,7 +36,13 @@ function isCallingCyGet (node) {
 function isDataArgument (node) {
   return node.arguments.length > 0 &&
     (
-      (node.arguments[0].type === 'Literal' && String(node.arguments[0].value).startsWith('[data-')) ||
-      (node.arguments[0].type === 'TemplateLiteral' && String(node.arguments[0].quasis[0].value.cooked).startsWith('[data-'))
+      (node.arguments[0].type === 'Literal' && isAliasOrDataSelector(String(node.arguments[0].value))) ||
+      (node.arguments[0].type === 'TemplateLiteral' && isAliasOrDataSelector(String(node.arguments[0].quasis[0].value.cooked)))
     )
 }
+
+function isAliasOrDataSelector (selector) {
+  return ['[data-', '@'].some(function (validValue) {
+    return selector.startsWith(validValue)
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-cypress",
-  "version": "2.10.3",
+  "version": "2.11.3",
   "description": "An ESLint plugin for projects using Cypress",
   "main": "index.js",
   "author": "Chris Breiding (chris@cypress.io)",
@@ -35,10 +35,13 @@
   },
   "scripts": {
     "precommit": "npm run lint",
-    "lint": "eslint *.js",
+    "lint": "eslint '*.js' '**/**/*.js'",
+    "lint-fix": "npm run lint -- --fix",
     "semantic-release": "semantic-release",
     "start": "yarn 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": {

package/tests/config.js

@@ -1,3 +1,4 @@
+/* global describe, it, expect */
 'use strict'
 
 const globals = require('globals')
@@ -9,17 +10,17 @@ describe('environments globals', () => {
   it('should not mutate globals', () => {
     expect(globals.browser).not.toHaveProperty('cy')
     expect(globals.mocha).not.toHaveProperty('cy')
-  });
+  })
 
   it('should include other globals', () => {
     expect(env.globals).toEqual(expect.objectContaining(globals.browser))
     expect(env.globals).toEqual(expect.objectContaining(globals.mocha))
-  });
+  })
 
   it('should include cypress globals', () => {
     expect(env.globals).toEqual(expect.objectContaining({
       cy: false,
       Cypress: false,
     }))
-  });
+  })
 })

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

@@ -16,6 +16,7 @@ ruleTester.run('no-assigning-return-values', rule, {
     { code: 'const foo = bar();', parserOptions },
     { code: 'const foo = bar().baz();', parserOptions },
     { code: 'const spy = cy.spy();', parserOptions },
+    { code: 'const spy = cy.spy().as();', parserOptions },
     { code: 'const stub = cy.stub();', parserOptions },
     { code: 'const result = cy.now();', parserOptions },
     { code: 'const state = cy.state();', parserOptions },

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

@@ -0,0 +1,25 @@
+'use strict'
+
+const rule = require('../../../lib/rules/no-async-tests')
+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-tests', rule, {
+  valid: [
+    { code: 'it(\'a test case\', () => { cy.get(\'.someClass\'); })', parserOptions },
+    { code: 'it(\'a test case\', async () => { await somethingAsync(); })', parserOptions },
+    { code: 'async function nonTestFn () { return await somethingAsync(); }', parserOptions },
+    { code: 'const nonTestArrowFn = async () => { await somethingAsync(); }', parserOptions },
+  ],
+  invalid: [
+    { code: 'it(\'a test case\', async () => { cy.get(\'.someClass\'); })', parserOptions, errors },
+    { code: 'test(\'a test case\', async () => { cy.get(\'.someClass\'); })', parserOptions, errors },
+    { code: 'it(\'a test case\', async function () { cy.get(\'.someClass\'); })', parserOptions, errors },
+    { code: 'test(\'a test case\', async function () { cy.get(\'.someClass\'); })', parserOptions, errors },
+  ],
+})

package/tests/lib/rules/no-force.js

@@ -9,7 +9,7 @@ const rule = require('../../../lib/rules/no-force')
 const RuleTester = require('eslint').RuleTester
 
 const errors = [{ messageId: 'unexpected' }]
-const parserOptions = { ecmaVersion: 6 }
+const parserOptions = { ecmaVersion: 2018 }
 
 //------------------------------------------------------------------------------
 // Tests
@@ -24,12 +24,13 @@ ruleTester.run('no-force', rule, {
     { code: `cy.get('button').click({multiple: true})`, parserOptions },
     { code: `cy.get('button').dblclick()`, parserOptions },
     { code: `cy.get('input').type('somth')`, parserOptions },
-    { code: `cy.get('input').type('somth', {anyoption: true})`, parserOptions, errors },
-    { code: `cy.get('input').trigger('click', {anyoption: true})`, parserOptions, errors },
-    { code: `cy.get('input').rightclick({anyoption: true})`, parserOptions, errors },
-    { code: `cy.get('input').check()`, parserOptions, errors },
-    { code: `cy.get('input').select()`, parserOptions, errors },
-    { code: `cy.get('input').focus()`, parserOptions, errors },
+    { code: `cy.get('input').type('somth', {anyoption: true})`, parserOptions },
+    { code: `cy.get('input').trigger('click', {anyoption: true})`, parserOptions },
+    { code: `cy.get('input').rightclick({anyoption: true})`, parserOptions },
+    { code: `cy.get('input').check()`, parserOptions },
+    { code: `cy.get('input').select()`, parserOptions },
+    { code: `cy.get('input').focus()`, parserOptions },
+    { code: `cy.document().trigger("keydown", { ...event })`, parserOptions },
   ],
 
   invalid: [

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

@@ -26,6 +26,29 @@ ruleTester.run('no-unnecessary-waiting', rule, {
     { code: 'const customWait = (alias = "@someRequest") => { cy.wait(alias) }', parserOptions, errors },
     { code: 'function customWait (ms) { cy.wait(ms) }', parserOptions, errors },
     { code: 'const customWait = (ms) => { cy.wait(ms) }', parserOptions, errors },
+
+    // disable the eslint rule
+    {
+      code: `
+        cy.wait(100); // eslint-disable-line no-unnecessary-waiting
+      `,
+      parserOptions,
+    },
+    {
+      code: `
+        /* eslint-disable-next-line no-unnecessary-waiting */
+        cy.wait(100)
+      `,
+      parserOptions,
+    },
+    {
+      code: `
+        /* eslint-disable no-unnecessary-waiting */
+        cy.wait(100)
+        /* eslint-enable no-unnecessary-waiting */
+      `,
+      parserOptions,
+    },
   ],
 
   invalid: [

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

@@ -16,6 +16,8 @@ ruleTester.run('require-data-selectors', rule, {
     { code: 'cy.scrollTo(0, 10)', parserOptions },
     { code: 'cy.tick(500)', parserOptions },
     { code: 'cy.get(\`[data-cy=${1}]\`)', parserOptions },
+    { code: 'cy.get("@my-alias")', parserOptions, errors },
+    { code: 'cy.get(`@my-alias`)', parserOptions, errors },
   ],
 
   invalid: [