eslint-plugin-jest 24.4.3 → 24.6.0

package/lib/rules/valid-expect-in-promise.js

@@ -9,96 +9,204 @@ var _experimentalUtils = require("@typescript-eslint/experimental-utils");
 
 var _utils = require("./utils");
 
-const isPromiseChainCall = node => node.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && node.callee.type === _experimentalUtils.AST_NODE_TYPES.MemberExpression && (0, _utils.isSupportedAccessor)(node.callee.property) && ['then', 'catch', 'finally'].includes((0, _utils.getAccessorValue)(node.callee.property));
-
-const isExpectCallPresentInFunction = body => {
-  if (body.type === _experimentalUtils.AST_NODE_TYPES.BlockStatement) {
-    return body.body.find(line => {
-      if (line.type === _experimentalUtils.AST_NODE_TYPES.ExpressionStatement) {
-        return isFullExpectCall(line.expression);
-      }
+const isPromiseChainCall = node => {
+  if (node.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && node.callee.type === _experimentalUtils.AST_NODE_TYPES.MemberExpression && (0, _utils.isSupportedAccessor)(node.callee.property)) {
+    // promise methods should have at least 1 argument
+    if (node.arguments.length === 0) {
+      return false;
+    }
 
-      if (line.type === _experimentalUtils.AST_NODE_TYPES.ReturnStatement && line.argument) {
-        return isFullExpectCall(line.argument);
-      }
+    switch ((0, _utils.getAccessorValue)(node.callee.property)) {
+      case 'then':
+        return node.arguments.length < 3;
 
-      return false;
-    });
+      case 'catch':
+      case 'finally':
+        return node.arguments.length < 2;
+    }
   }
 
-  return isFullExpectCall(body);
+  return false;
 };
 
-const isFullExpectCall = expression => expression.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && (0, _utils.isExpectMember)(expression.callee);
+const findTopMostCallExpression = node => {
+  let topMostCallExpression = node;
+  let {
+    parent
+  } = node;
 
-const reportReturnRequired = (context, node) => {
-  context.report({
-    loc: {
-      end: {
-        column: node.loc.end.column,
-        line: node.loc.end.line
-      },
-      start: node.loc.start
-    },
-    messageId: 'returnPromise',
-    node
-  });
+  while (parent) {
+    if (parent.type === _experimentalUtils.AST_NODE_TYPES.CallExpression) {
+      topMostCallExpression = parent;
+      parent = parent.parent;
+      continue;
+    }
+
+    if (parent.type !== _experimentalUtils.AST_NODE_TYPES.MemberExpression) {
+      break;
+    }
+
+    parent = parent.parent;
+  }
+
+  return topMostCallExpression;
 };
 
-const isPromiseReturnedLater = (node, testFunctionBody) => {
-  let promiseName;
+const isTestCaseCallWithCallbackArg = node => {
+  if (!(0, _utils.isTestCaseCall)(node)) {
+    return false;
+  }
+
+  const isJestEach = (0, _utils.getNodeName)(node).endsWith('.each');
 
-  if (node.type === _experimentalUtils.AST_NODE_TYPES.ExpressionStatement && node.expression.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && node.expression.callee.type === _experimentalUtils.AST_NODE_TYPES.MemberExpression && (0, _utils.isSupportedAccessor)(node.expression.callee.object)) {
-    promiseName = (0, _utils.getAccessorValue)(node.expression.callee.object);
-  } else if (node.type === _experimentalUtils.AST_NODE_TYPES.VariableDeclarator && node.id.type === _experimentalUtils.AST_NODE_TYPES.Identifier) {
-    promiseName = node.id.name;
+  if (isJestEach && node.callee.type !== _experimentalUtils.AST_NODE_TYPES.TaggedTemplateExpression) {
+    // isJestEach but not a TaggedTemplateExpression, so this must be
+    // the `jest.each([])()` syntax which this rule doesn't support due
+    // to its complexity (see jest-community/eslint-plugin-jest#710)
+    // so we return true to trigger bailout
+    return true;
   }
 
-  const lastLineInTestFunc = testFunctionBody[testFunctionBody.length - 1];
-  return lastLineInTestFunc.type === _experimentalUtils.AST_NODE_TYPES.ReturnStatement && lastLineInTestFunc.argument && ('name' in lastLineInTestFunc.argument && lastLineInTestFunc.argument.name === promiseName || !promiseName);
+  if (isJestEach || node.arguments.length >= 2) {
+    const [, callback] = node.arguments;
+    const callbackArgIndex = Number(isJestEach);
+    return callback && (0, _utils.isFunction)(callback) && callback.params.length === 1 + callbackArgIndex;
+  }
+
+  return false;
 };
 
-const findTestFunction = node => {
-  while (node) {
-    var _node$parent;
+const isPromiseMethodThatUsesValue = (node, identifier) => {
+  const {
+    name
+  } = identifier;
+
+  if (node.argument === null) {
+    return false;
+  }
+
+  if (node.argument.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && node.argument.arguments.length > 0) {
+    const nodeName = (0, _utils.getNodeName)(node.argument);
+
+    if (['Promise.all', 'Promise.allSettled'].includes(nodeName)) {
+      const [firstArg] = node.argument.arguments;
 
-    if ((0, _utils.isFunction)(node) && ((_node$parent = node.parent) === null || _node$parent === void 0 ? void 0 : _node$parent.type) === _experimentalUtils.AST_NODE_TYPES.CallExpression && (0, _utils.isTestCaseCall)(node.parent)) {
-      return node;
+      if (firstArg.type === _experimentalUtils.AST_NODE_TYPES.ArrayExpression && firstArg.elements.some(nod => (0, _utils.isIdentifier)(nod, name))) {
+        return true;
+      }
     }
 
-    node = node.parent;
+    if (['Promise.resolve', 'Promise.reject'].includes(nodeName) && node.argument.arguments.length === 1) {
+      return (0, _utils.isIdentifier)(node.argument.arguments[0], name);
+    }
   }
 
-  return null;
+  return node.argument.type === _experimentalUtils.AST_NODE_TYPES.Identifier && (0, _utils.isIdentifier)(node.argument, name);
 };
+/**
+ * Attempts to determine if the runtime value represented by the given `identifier`
+ * is `await`ed or `return`ed within the given `body` of statements
+ */
 
-const isParentThenOrPromiseReturned = (node, testFunctionBody) => node.type === _experimentalUtils.AST_NODE_TYPES.ReturnStatement || isPromiseReturnedLater(node, testFunctionBody);
 
-const verifyExpectWithReturn = (promiseCallbacks, node, context, testFunctionBody) => {
-  promiseCallbacks.some(promiseCallback => {
-    if (promiseCallback && (0, _utils.isFunction)(promiseCallback)) {
-      if (isExpectCallPresentInFunction(promiseCallback.body) && node.parent.parent && !isParentThenOrPromiseReturned(node.parent.parent, testFunctionBody)) {
-        reportReturnRequired(context, node.parent.parent);
-        return true;
+const isValueAwaitedOrReturned = (identifier, body) => {
+  const {
+    name
+  } = identifier;
+
+  for (const node of body) {
+    // skip all nodes that are before this identifier, because they'd probably
+    // be affecting a different runtime value (e.g. due to reassignment)
+    if (node.range[0] <= identifier.range[0]) {
+      continue;
+    }
+
+    if (node.type === _experimentalUtils.AST_NODE_TYPES.ReturnStatement) {
+      return isPromiseMethodThatUsesValue(node, identifier);
+    }
+
+    if (node.type === _experimentalUtils.AST_NODE_TYPES.ExpressionStatement) {
+      if (node.expression.type === _experimentalUtils.AST_NODE_TYPES.AwaitExpression) {
+        return isPromiseMethodThatUsesValue(node.expression, identifier);
+      } // (re)assignment changes the runtime value, so if we've not found an
+      // await or return already we act as if we've reached the end of the body
+
+
+      if (node.expression.type === _experimentalUtils.AST_NODE_TYPES.AssignmentExpression) {
+        var _getNodeName;
+
+        // unless we're assigning to the same identifier, in which case
+        // we might be chaining off the existing promise value
+        if ((0, _utils.isIdentifier)(node.expression.left, name) && (_getNodeName = (0, _utils.getNodeName)(node.expression.right)) !== null && _getNodeName !== void 0 && _getNodeName.startsWith(`${name}.`) && isPromiseChainCall(node.expression.right)) {
+          continue;
+        }
+
+        break;
       }
     }
 
-    return false;
-  });
+    if (node.type === _experimentalUtils.AST_NODE_TYPES.BlockStatement && isValueAwaitedOrReturned(identifier, node.body)) {
+      return true;
+    }
+  }
+
+  return false;
 };
 
-const isHavingAsyncCallBackParam = testFunction => testFunction.params[0] && testFunction.params[0].type === _experimentalUtils.AST_NODE_TYPES.Identifier;
+const findFirstBlockBodyUp = node => {
+  let parent = node;
+
+  while (parent) {
+    if (parent.type === _experimentalUtils.AST_NODE_TYPES.BlockStatement) {
+      return parent.body;
+    }
+
+    parent = parent.parent;
+  }
+  /* istanbul ignore next */
+
+
+  throw new Error(`Could not find BlockStatement - please file a github issue at https://github.com/jest-community/eslint-plugin-jest`);
+};
+
+const isDirectlyWithinTestCaseCall = node => {
+  let parent = node;
+
+  while (parent) {
+    if ((0, _utils.isFunction)(parent)) {
+      var _parent;
+
+      parent = parent.parent;
+      return !!(((_parent = parent) === null || _parent === void 0 ? void 0 : _parent.type) === _experimentalUtils.AST_NODE_TYPES.CallExpression && (0, _utils.isTestCaseCall)(parent));
+    }
+
+    parent = parent.parent;
+  }
+
+  return false;
+};
+
+const isVariableAwaitedOrReturned = variable => {
+  const body = findFirstBlockBodyUp(variable); // it's pretty much impossible for us to track destructuring assignments,
+  // so we return true to bailout gracefully
+
+  if (!(0, _utils.isIdentifier)(variable.id)) {
+    return true;
+  }
+
+  return isValueAwaitedOrReturned(variable.id, body);
+};
 
 var _default = (0, _utils.createRule)({
   name: __filename,
   meta: {
     docs: {
       category: 'Best Practices',
-      description: 'Enforce having return statement when testing with promises',
+      description: 'Ensure promises that have expectations in their chain are valid',
       recommended: 'error'
     },
     messages: {
-      returnPromise: 'Promise should be returned to test its fulfillment or rejection'
+      expectInFloatingPromise: "This promise should either be returned or awaited to ensure the expects in it's chain are called"
     },
     type: 'suggestion',
     schema: []
@@ -106,30 +214,106 @@ var _default = (0, _utils.createRule)({
   defaultOptions: [],
 
   create(context) {
+    let inTestCaseWithDoneCallback = false; // an array of booleans representing each promise chain we enter, with the
+    // boolean value representing if we think a given chain contains an expect
+    // in it's body.
+    //
+    // since we only care about the inner-most chain, we represent the state in
+    // reverse with the inner-most being the first item, as that makes it
+    // slightly less code to assign to by not needing to know the length
+
+    const chains = [];
     return {
       CallExpression(node) {
-        if (!isPromiseChainCall(node) || node.parent && node.parent.type === _experimentalUtils.AST_NODE_TYPES.AwaitExpression) {
+        // there are too many ways that the done argument could be used with
+        // promises that contain expect that would make the promise safe for us
+        if (isTestCaseCallWithCallbackArg(node)) {
+          inTestCaseWithDoneCallback = true;
           return;
-        }
+        } // if this call expression is a promise chain, add it to the stack with
+        // value of "false", as we assume there are no expect calls initially
 
-        const testFunction = findTestFunction(node);
 
-        if (testFunction && !isHavingAsyncCallBackParam(testFunction)) {
-          const {
-            body
-          } = testFunction;
+        if (isPromiseChainCall(node)) {
+          chains.unshift(false);
+          return;
+        } // if we're within a promise chain, and this call expression looks like
+        // an expect call, mark the deepest chain as having an expect call
 
-          if (body.type !== _experimentalUtils.AST_NODE_TYPES.BlockStatement) {
-            return;
+
+        if (chains.length > 0 && (0, _utils.isExpectCall)(node)) {
+          chains[0] = true;
+        }
+      },
+
+      'CallExpression:exit'(node) {
+        // there are too many ways that the "done" argument could be used to
+        // make promises containing expects safe in a test for us to be able to
+        // accurately check, so we just bail out completely if it's present
+        if (inTestCaseWithDoneCallback) {
+          if ((0, _utils.isTestCaseCall)(node)) {
+            inTestCaseWithDoneCallback = false;
           }
 
-          const testFunctionBody = body.body; // then block can have two args, fulfillment & rejection
-          // then block can have one args, fulfillment
-          // catch block can have one args, rejection
-          // ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+          return;
+        }
+
+        if (!isPromiseChainCall(node)) {
+          return;
+        } // since we're exiting this call expression (which is a promise chain)
+        // we remove it from the stack of chains, since we're unwinding
+
+
+        const hasExpectCall = chains.shift(); // if the promise chain we're exiting doesn't contain an expect,
+        // then we don't need to check it for anything
+
+        if (!hasExpectCall) {
+          return;
+        }
+
+        const {
+          parent
+        } = findTopMostCallExpression(node); // if we don't have a parent (which is technically impossible at runtime)
+        // or our parent is not directly within the test case, we stop checking
+        // because we're most likely in the body of a function being defined
+        // within the test, which we can't track
 
-          verifyExpectWithReturn(node.arguments.slice(0, 2), node.callee, context, testFunctionBody);
+        if (!parent || !isDirectlyWithinTestCaseCall(parent)) {
+          return;
         }
+
+        switch (parent.type) {
+          case _experimentalUtils.AST_NODE_TYPES.VariableDeclarator:
+            {
+              if (isVariableAwaitedOrReturned(parent)) {
+                return;
+              }
+
+              break;
+            }
+
+          case _experimentalUtils.AST_NODE_TYPES.AssignmentExpression:
+            {
+              if (parent.left.type === _experimentalUtils.AST_NODE_TYPES.Identifier && isValueAwaitedOrReturned(parent.left, findFirstBlockBodyUp(parent))) {
+                return;
+              }
+
+              break;
+            }
+
+          case _experimentalUtils.AST_NODE_TYPES.ExpressionStatement:
+            break;
+
+          case _experimentalUtils.AST_NODE_TYPES.ReturnStatement:
+          case _experimentalUtils.AST_NODE_TYPES.AwaitExpression:
+          default:
+            return;
+        }
+
+        context.report({
+          messageId: 'expectInFloatingPromise',
+          node: parent
+        });
       }
 
     };

package/lib/rules/valid-expect.js

@@ -26,19 +26,25 @@ const getPromiseCallExpressionNode = node => {
     node = node.parent;
   }
 
-  if (node.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && node.callee && node.callee.type === _experimentalUtils.AST_NODE_TYPES.MemberExpression && (0, _utils.isSupportedAccessor)(node.callee.object) && (0, _utils.getAccessorValue)(node.callee.object) === 'Promise' && node.parent) {
+  if (node.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && node.callee.type === _experimentalUtils.AST_NODE_TYPES.MemberExpression && (0, _utils.isSupportedAccessor)(node.callee.object) && (0, _utils.getAccessorValue)(node.callee.object) === 'Promise' && node.parent) {
     return node;
   }
 
   return null;
 };
 
-const findPromiseCallExpressionNode = node => node.parent && node.parent.parent && [_experimentalUtils.AST_NODE_TYPES.CallExpression, _experimentalUtils.AST_NODE_TYPES.ArrayExpression].includes(node.parent.type) ? getPromiseCallExpressionNode(node.parent) : null;
+const findPromiseCallExpressionNode = node => {
+  var _node$parent;
+
+  return (_node$parent = node.parent) !== null && _node$parent !== void 0 && _node$parent.parent && [_experimentalUtils.AST_NODE_TYPES.CallExpression, _experimentalUtils.AST_NODE_TYPES.ArrayExpression].includes(node.parent.type) ? getPromiseCallExpressionNode(node.parent) : null;
+};
 
 const getParentIfThenified = node => {
-  const grandParentNode = node.parent && node.parent.parent;
+  var _node$parent2;
+
+  const grandParentNode = (_node$parent2 = node.parent) === null || _node$parent2 === void 0 ? void 0 : _node$parent2.parent;
 
-  if (grandParentNode && grandParentNode.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && grandParentNode.callee && (0, _utils.isExpectMember)(grandParentNode.callee) && ['then', 'catch'].includes((0, _utils.getAccessorValue)(grandParentNode.callee.property)) && grandParentNode.parent) {
+  if (grandParentNode && grandParentNode.type === _experimentalUtils.AST_NODE_TYPES.CallExpression && (0, _utils.isExpectMember)(grandParentNode.callee) && ['then', 'catch'].includes((0, _utils.getAccessorValue)(grandParentNode.callee.property)) && grandParentNode.parent) {
     // Just in case `then`s are chained look one above.
     return getParentIfThenified(grandParentNode);
   }

package/lib/rules/valid-title.js

@@ -25,23 +25,38 @@ const doesBinaryExpressionContainStringNode = binaryExp => {
 
 const quoteStringValue = node => node.type === _experimentalUtils.AST_NODE_TYPES.TemplateLiteral ? `\`${node.quasis[0].value.raw}\`` : node.raw;
 
+const compileMatcherPattern = matcherMaybeWithMessage => {
+  const [matcher, message] = Array.isArray(matcherMaybeWithMessage) ? matcherMaybeWithMessage : [matcherMaybeWithMessage];
+  return [new RegExp(matcher, 'u'), message];
+};
+
 const compileMatcherPatterns = matchers => {
-  if (typeof matchers === 'string') {
-    const matcher = new RegExp(matchers, 'u');
+  if (typeof matchers === 'string' || Array.isArray(matchers)) {
+    const compiledMatcher = compileMatcherPattern(matchers);
     return {
-      describe: matcher,
-      test: matcher,
-      it: matcher
+      describe: compiledMatcher,
+      test: compiledMatcher,
+      it: compiledMatcher
     };
   }
 
   return {
-    describe: matchers.describe ? new RegExp(matchers.describe, 'u') : null,
-    test: matchers.test ? new RegExp(matchers.test, 'u') : null,
-    it: matchers.it ? new RegExp(matchers.it, 'u') : null
+    describe: matchers.describe ? compileMatcherPattern(matchers.describe) : null,
+    test: matchers.test ? compileMatcherPattern(matchers.test) : null,
+    it: matchers.it ? compileMatcherPattern(matchers.it) : null
   };
 };
 
+const MatcherAndMessageSchema = {
+  type: 'array',
+  items: {
+    type: 'string'
+  },
+  minItems: 1,
+  maxItems: 2,
+  additionalItems: false
+};
+
 var _default = (0, _utils.createRule)({
   name: __filename,
   meta: {
@@ -57,7 +72,9 @@ var _default = (0, _utils.createRule)({
       accidentalSpace: 'should not have leading or trailing spaces',
       disallowedWord: '"{{ word }}" is not allowed in test titles.',
       mustNotMatch: '{{ jestFunctionName }} should not match {{ pattern }}',
-      mustMatch: '{{ jestFunctionName }} should match {{ pattern }}'
+      mustMatch: '{{ jestFunctionName }} should match {{ pattern }}',
+      mustNotMatchCustom: '{{ message }}',
+      mustMatchCustom: '{{ message }}'
     },
     type: 'suggestion',
     schema: [{
@@ -72,43 +89,22 @@ var _default = (0, _utils.createRule)({
           items: {
             type: 'string'
           }
-        },
-        mustNotMatch: {
+        }
+      },
+      patternProperties: {
+        [/^must(?:Not)?Match$/u.source]: {
           oneOf: [{
             type: 'string'
-          }, {
+          }, MatcherAndMessageSchema, {
             type: 'object',
-            properties: {
-              describe: {
-                type: 'string'
-              },
-              test: {
-                type: 'string'
-              },
-              it: {
-                type: 'string'
-              }
+            propertyNames: {
+              enum: ['describe', 'test', 'it']
             },
-            additionalProperties: false
-          }]
-        },
-        mustMatch: {
-          oneOf: [{
-            type: 'string'
-          }, {
-            type: 'object',
-            properties: {
-              describe: {
+            additionalProperties: {
+              oneOf: [{
                 type: 'string'
-              },
-              test: {
-                type: 'string'
-              },
-              it: {
-                type: 'string'
-              }
-            },
-            additionalProperties: false
+              }, MatcherAndMessageSchema]
+            }
           }]
         }
       },
@@ -132,6 +128,8 @@ var _default = (0, _utils.createRule)({
     const mustMatchPatterns = compileMatcherPatterns(mustMatch !== null && mustMatch !== void 0 ? mustMatch : {});
     return {
       CallExpression(node) {
+        var _mustNotMatchPatterns, _mustMatchPatterns$je;
+
         if (!(0, _utils.isDescribeCall)(node) && !(0, _utils.isTestCaseCall)(node)) {
           return;
         }
@@ -205,32 +203,34 @@ var _default = (0, _utils.createRule)({
         }
 
         const [jestFunctionName] = nodeName.split('.');
-        const mustNotMatchPattern = mustNotMatchPatterns[jestFunctionName];
+        const [mustNotMatchPattern, mustNotMatchMessage] = (_mustNotMatchPatterns = mustNotMatchPatterns[jestFunctionName]) !== null && _mustNotMatchPatterns !== void 0 ? _mustNotMatchPatterns : [];
 
         if (mustNotMatchPattern) {
           if (mustNotMatchPattern.test(title)) {
             context.report({
-              messageId: 'mustNotMatch',
+              messageId: mustNotMatchMessage ? 'mustNotMatchCustom' : 'mustNotMatch',
               node: argument,
               data: {
                 jestFunctionName,
-                pattern: mustNotMatchPattern
+                pattern: mustNotMatchPattern,
+                message: mustNotMatchMessage
               }
             });
             return;
           }
         }
 
-        const mustMatchPattern = mustMatchPatterns[jestFunctionName];
+        const [mustMatchPattern, mustMatchMessage] = (_mustMatchPatterns$je = mustMatchPatterns[jestFunctionName]) !== null && _mustMatchPatterns$je !== void 0 ? _mustMatchPatterns$je : [];
 
         if (mustMatchPattern) {
           if (!mustMatchPattern.test(title)) {
             context.report({
-              messageId: 'mustMatch',
+              messageId: mustMatchMessage ? 'mustMatchCustom' : 'mustMatch',
               node: argument,
               data: {
                 jestFunctionName,
-                pattern: mustMatchPattern
+                pattern: mustMatchPattern,
+                message: mustMatchMessage
               }
             });
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "24.4.3",
+  "version": "24.6.0",
   "description": "Eslint rules for Jest",
   "keywords": [
     "eslint",