eslint-plugin-cypress 2.1.1 → 2.2.1

package/README.md

@@ -21,9 +21,6 @@ Add an `.eslintrc.json` file to your `cypress` directory with the following:
   "plugins": [
     "cypress"
   ],
-  "extends": [
-    "plugin:cypress/recommended"
-  ],
   "env": {
     "cypress/globals": true
   }
@@ -32,21 +29,27 @@ Add an `.eslintrc.json` file to your `cypress` directory with the following:
 
 ## Rules
 
-Rules are grouped by category to help you understand their purpose.
+These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices). Use them by adding the following to your eslint config:
 
-Rules with a check mark (✅) are enabled by default while using
-the `plugin:cypress/recommended` config.
+```json
+// my-project/cypress/.eslintrc.json
 
-The --fix option on the command line automatically fixes problems reported by
-rules which have a wrench (🔧) below.
+{
+  "extends": [
+    "plugin:cypress/recommended"
+  ]
+}
+```
 
+Rules with a check mark (✅) are enabled by default while using the `plugin:cypress/recommended` config.
 
-### Possible Errors
+**NOTE**: These rules currently require eslint 5.0 or greater. If you would like support added for eslint 4.x, please 👍  [this issue](https://github.com/cypress-io/eslint-plugin-cypress/issues/14).
 
 |    | Rule ID | Description |
 |:---|:--------|:------------|
 | ✅ | [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 |
+| | [assertion-before-screenshot](./docs/rules/assertion-before-screenshot.md) | Ensure screenshots are preceded by an assertion |
 
 ## Chai and `no-unused-expressions`
 

package/docs/rules/assertion-before-screenshot.md

@@ -0,0 +1,22 @@
+## Assertion Before Screenshot
+
+If you take screenshots without assertions then you may get different screenshots depending on timing.
+
+For example, if clicking a button makes some network calls and upon success, renders something, then the screenshot may sometimes have the new render and sometimes not.
+
+This rule checks there is an assertion making sure your application state is correct before doing a screenshot. This makes sure the result of the screenshot will be consistent.
+
+Invalid:
+
+```
+cy.visit('myUrl');
+cy.screenshot();
+```
+
+Valid:
+
+```
+cy.visit('myUrl');
+cy.get('[data-test-id="my-element"]').should('be.visible');
+cy.screenshot();
+```

package/docs/rules/no-assigning-return-values.md

@@ -1,3 +1,3 @@
 ## No Assigning Return Values
 
-See [the Cypress Best Practices guide](https://docs.cypress.io/guides/references/best-practices.html#Assigning-Return-Values).
+See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Assigning-Return-Values).

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

@@ -1,3 +1,3 @@
 ## No Assigning Return Values
 
-See [the Cypress Best Practices guide](https://docs.cypress.io/guides/references/best-practices.html#Unnecessary-Waiting).
+See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Unnecessary-Waiting).

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'),
+    'assertion-before-screenshot': require('./lib/rules/assertion-before-screenshot'),
   },
   configs: {
     recommended: require('./lib/config/recommended'),
@@ -15,6 +16,7 @@ module.exports = {
         Cypress: false,
         expect: false,
         assert: false,
+        chai: false,
       }),
       parserOptions: {
         ecmaVersion: 2017,

package/lib/config/recommended.js

@@ -1,9 +1,9 @@
-'use strict';
+'use strict'
 
 module.exports = {
   plugins: ['cypress'],
   rules: {
     'cypress/no-assigning-return-values': 'error',
-    'cypress/no-unnecessary-waiting': 'error'
-  }
-};
+    'cypress/no-unnecessary-waiting': 'error',
+  },
+}

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

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Assert on the page state before taking a screenshot, so the screenshot is consistent
+ * @author Luke Page
+ */
+
+'use strict'
+
+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: {
+    docs: {
+      description: 'Assert on the page state before taking a screenshot, so the screenshot is consistent',
+      category: 'Possible Errors',
+      recommended: false,
+    },
+    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 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' &&
+         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-assigning-return-values.js

@@ -3,7 +3,18 @@
  * @author Elad Shahar
  */
 
-'use strict';
+'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: {
@@ -11,36 +22,45 @@ module.exports = {
       description: 'Prevent assigning return values of cy calls',
       category: 'Possible Errors',
       recommended: true,
-      url: 'https://docs.cypress.io/guides/references/best-practices.html#Assigning-Return-Values'
+      url: 'https://on.cypress.io/best-practices#Assigning-Return-Values',
     },
     schema: [],
     messages: {
-      unexpected: 'Do not assign the return value of a Cypress command'
-    }
+      unexpected: 'Do not assign the return value of a Cypress command',
+    },
   },
-  create(context) {
+  create (context) {
     return {
-      VariableDeclaration(node) {
+      VariableDeclaration (node) {
         if (node.declarations.some(isCypressCommandDeclaration)) {
-          context.report({ node, messageId: 'unexpected' });
+          context.report({ node, messageId: 'unexpected' })
         }
-      }
-    };
-  }
-};
+      },
+    }
+  },
+}
 
-function isCypressCommandDeclaration(declarator) {
-  if (!declarator)             { return; }
-  if (!declarator.init)        { return; }
-  if (!declarator.init.callee) { return; }
+const whitelistedCommands = {
+  now: true,
+  spy: true,
+  state: true,
+  stub: true,
+}
 
-  let object = declarator.init.callee.object;
+function isCypressCommandDeclaration (declarator) {
+  let object = get(declarator, 'init.callee.object')
 
-  if (!object)                 { return; }
+  if (!object) return
 
   while (object.callee) {
-    object = object.callee.object;
+    object = object.callee.object
+
+    if (!object) return
   }
 
-  return object.name === 'cy';
+  const commandName = get(object, 'parent.property.name')
+
+  if (commandName && whitelistedCommands[commandName]) return
+
+  return object.name === 'cy'
 }

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

@@ -3,7 +3,7 @@
  * @author Elad Shahar
  */
 
-'use strict';
+'use strict'
 
 module.exports = {
   meta: {
@@ -11,34 +11,34 @@ module.exports = {
       description: 'Prevent waiting for arbitrary time periods',
       category: 'Possible Errors',
       recommended: true,
-      url: 'https://docs.cypress.io/guides/references/best-practices.html#Unnecessary-Waiting'
+      url: 'https://on.cypress.io/best-practices#Unnecessary-Waiting',
     },
     schema: [],
     messages: {
-      unexpected: 'Do not wait for arbitrary time periods'
-    }
+      unexpected: 'Do not wait for arbitrary time periods',
+    },
   },
-  create(context) {
+  create (context) {
     return {
-      CallExpression(node) {
+      CallExpression (node) {
         if (isCallingCyWait(node) && isNumberArgument(node)) {
-          context.report({ node, messageId: 'unexpected' });
+          context.report({ node, messageId: 'unexpected' })
         }
-      }
-    };
-  }
-};
+      },
+    }
+  },
+}
 
-function isCallingCyWait(node) {
+function isCallingCyWait (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 === 'wait';
+         node.callee.property.name === 'wait'
 }
 
-function isNumberArgument(node) {
+function isNumberArgument (node) {
   return node.arguments.length > 0 &&
          node.arguments[0].type === 'Literal' &&
-         typeof(node.arguments[0].value) === 'number';
+         typeof (node.arguments[0].value) === 'number'
 }

package/package.json

@@ -1 +1 @@
-{"name":"eslint-plugin-cypress","version":"2.1.1","description":"An ESLint plugin for projects using Cypress","main":"index.js","author":"Chris Breiding (chris@cypress.io)","license":"MIT","keywords":["eslint","eslintplugin","cypress"],"repository":{"type":"git","url":"git+https://github.com/cypress-io/eslint-plugin-cypress.git"},"bugs":{"url":"https://github.com/cypress-io/eslint-plugin-cypress/issues"},"homepage":"https://github.com/cypress-io/eslint-plugin-cypress#readme","peerDependencies":{"eslint":">= 3.2.1"},"dependencies":{"globals":"^11.0.1"},"devDependencies":{"condition-circle":"1.5.0","eslint":"^5.7.0","eslint-plugin-cypress-dev":"1.1.2","github-post-release":"1.13.1","husky":"^0.14.3","jest":"^23.6.0","semantic-release":"8.2.0","simple-commit-message":"3.3.1"},"scripts":{"precommit":"npm run lint","lint":"eslint *.js","semantic-release":"semantic-release pre && npm publish --access public && semantic-release post","start":"yarn run test:watch","test":"jest","test-watch":"jest --watchAll"},"release":{"verifyConditions":"condition-circle","analyzeCommits":"simple-commit-message","generateNotes":"github-post-release"},"jest":{"testMatch":["**/tests/**/*.js"]}}
+{"name":"eslint-plugin-cypress","version":"2.2.1","description":"An ESLint plugin for projects using Cypress","main":"index.js","author":"Chris Breiding (chris@cypress.io)","license":"MIT","keywords":["eslint","eslintplugin","cypress"],"repository":{"type":"git","url":"git+https://github.com/cypress-io/eslint-plugin-cypress.git"},"bugs":{"url":"https://github.com/cypress-io/eslint-plugin-cypress/issues"},"homepage":"https://github.com/cypress-io/eslint-plugin-cypress#readme","peerDependencies":{"eslint":">= 3.2.1"},"dependencies":{"globals":"^11.0.1"},"devDependencies":{"condition-circle":"1.5.0","eslint":"^5.7.0","eslint-plugin-cypress-dev":"1.1.2","github-post-release":"1.13.1","husky":"^0.14.3","jest":"^23.6.0","semantic-release":"8.2.0","simple-commit-message":"3.3.1"},"scripts":{"precommit":"npm run lint","lint":"eslint *.js","semantic-release":"semantic-release pre && npm publish --access public && semantic-release post","start":"yarn run test:watch","test":"jest","test-watch":"jest --watchAll"},"release":{"verifyConditions":"condition-circle","analyzeCommits":"simple-commit-message","generateNotes":"github-post-release"},"jest":{"testMatch":["**/tests/**/*.js"]}}

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

@@ -0,0 +1,35 @@
+'use strict'
+
+const rule = require('../../../lib/rules/assertion-before-screenshot')
+const RuleTester = require('eslint').RuleTester
+
+const ruleTester = new RuleTester()
+
+const errors = [{ messageId: 'unexpected' }]
+const parserOptions = { ecmaVersion: 6 }
+
+ruleTester.run('assertion-before-screenshot', rule, {
+  valid: [
+    { code: 'cy.get(".some-element"); cy.screenshot();', parserOptions },
+    { code: 'cy.get(".some-element").should("exist").screenshot();', parserOptions },
+    { code: 'cy.get(".some-element").should("exist").screenshot().click()', parserOptions, errors },
+    { code: 'cy.get(".some-element").should("exist"); if(true) cy.screenshot();', parserOptions },
+    { code: 'if(true) { cy.get(".some-element").should("exist"); cy.screenshot(); }', parserOptions },
+    { code: 'cy.get(".some-element").should("exist"); if(true) { cy.screenshot(); }', parserOptions },
+    { code: 'const a = () => { cy.get(".some-element").should("exist"); cy.screenshot(); }', parserOptions, errors },
+    { code: 'cy.get(".some-element").should("exist").and("be.visible"); cy.screenshot();', parserOptions },
+    { code: 'cy.get(".some-element").contains("Text"); cy.screenshot();', parserOptions },
+  ],
+
+  invalid: [
+    { code: 'cy.screenshot()', parserOptions, errors },
+    { code: 'cy.visit("somepage"); cy.screenshot();', parserOptions, errors },
+    { code: 'cy.custom(); cy.screenshot()', parserOptions, errors },
+    { code: 'cy.get(".some-element").click(); cy.screenshot()', parserOptions, errors },
+    { code: 'cy.get(".some-element").click().screenshot()', parserOptions, errors },
+    { code: 'if(true) { cy.get(".some-element").click(); cy.screenshot(); }', parserOptions, errors },
+    { code: 'cy.get(".some-element").click(); if(true) { cy.screenshot(); }', parserOptions, errors },
+    { code: 'cy.get(".some-element"); function a() { cy.screenshot(); }', parserOptions, errors },
+    { code: 'cy.get(".some-element"); const a = () => { cy.screenshot(); }', parserOptions, errors },
+  ],
+})

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

@@ -1,12 +1,12 @@
-"use strict";
+'use strict'
 
-const rule = require('../../../lib/rules/no-assigning-return-values');
-const RuleTester = require('eslint').RuleTester;
+const rule = require('../../../lib/rules/no-assigning-return-values')
+const RuleTester = require('eslint').RuleTester
 
-const ruleTester = new RuleTester();
+const ruleTester = new RuleTester()
 
-const errors = [{ messageId: 'unexpected' }];
-const parserOptions = { ecmaVersion: 6 };
+const errors = [{ messageId: 'unexpected' }]
+const parserOptions = { ecmaVersion: 6 }
 
 ruleTester.run('no-assigning-return-values', rule, {
   valid: [
@@ -14,8 +14,13 @@ ruleTester.run('no-assigning-return-values', rule, {
     { code: 'let foo = true;', parserOptions },
     { code: 'const foo = true;', parserOptions },
     { code: 'const foo = bar();', parserOptions },
+    { code: 'const foo = bar().baz();', parserOptions },
+    { code: 'const spy = cy.spy();', parserOptions },
+    { code: 'const stub = cy.stub();', parserOptions },
+    { code: 'const result = cy.now();', parserOptions },
+    { code: 'const state = cy.state();', parserOptions },
     { code: 'cy.get("foo");', parserOptions },
-    { code: 'cy.contains("foo").click();', parserOptions }
+    { code: 'cy.contains("foo").click();', parserOptions },
   ],
 
   invalid: [
@@ -27,6 +32,6 @@ ruleTester.run('no-assigning-return-values', rule, {
     { code: 'let a = cy.window()', parserOptions, errors },
     { code: 'let a = cy.wait("@something")', parserOptions, errors },
 
-    { code: 'let a = cy.contains("foo").click()', parserOptions, errors }
-  ]
-});
+    { code: 'let a = cy.contains("foo").click()', parserOptions, errors },
+  ],
+})

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

@@ -1,12 +1,12 @@
-"use strict";
+'use strict'
 
-const rule = require('../../../lib/rules/no-unnecessary-waiting');
-const RuleTester = require('eslint').RuleTester;
+const rule = require('../../../lib/rules/no-unnecessary-waiting')
+const RuleTester = require('eslint').RuleTester
 
-const ruleTester = new RuleTester();
+const ruleTester = new RuleTester()
 
-const errors = [{ messageId: 'unexpected' }];
-const parserOptions = { ecmaVersion: 6 };
+const errors = [{ messageId: 'unexpected' }]
+const parserOptions = { ecmaVersion: 6 }
 
 ruleTester.run('no-unnecessary-waiting', rule, {
   valid: [
@@ -15,14 +15,14 @@ ruleTester.run('no-unnecessary-waiting', rule, {
     { code: 'cy.wait("@someRequest").then((xhr) => xhr)', parserOptions },
     { code: 'cy.wait(["@someRequest", "@anotherRequest"])', parserOptions },
 
-    { code: 'cy.clock(5000)', parserOptions},
+    { code: 'cy.clock(5000)', parserOptions },
     { code: 'cy.scrollTo(0, 10)', parserOptions },
-    { code: 'cy.tick(500)', parserOptions }
+    { code: 'cy.tick(500)', parserOptions },
   ],
 
   invalid: [
     { code: 'cy.wait(0)', parserOptions, errors },
     { code: 'cy.wait(100)', parserOptions, errors },
-    { code: 'cy.wait(5000)', parserOptions, errors }
-  ]
-});
+    { code: 'cy.wait(5000)', parserOptions, errors },
+  ],
+})