eslint-plugin-jest 24.5.2 → 24.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [24.6.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.5.2...v24.6.0) (2021-10-09)
+
+
+### Features
+
+* **valid-expect-in-promise:** re-implement rule ([#916](https://github.com/jest-community/eslint-plugin-jest/issues/916)) ([7a49c58](https://github.com/jest-community/eslint-plugin-jest/commit/7a49c5831e3d85a60c11e385203b8f83d98ad580))
+
 ## [24.5.2](https://github.com/jest-community/eslint-plugin-jest/compare/v24.5.1...v24.5.2) (2021-10-04)
 
 

package/README.md

@@ -193,7 +193,7 @@ installations requiring long-term consistency.
 | [require-top-level-describe](docs/rules/require-top-level-describe.md)       | Require test cases and hooks to be inside a `describe` block        |                  |              |
 | [valid-describe](docs/rules/valid-describe.md)                               | Enforce valid `describe()` callback                                 | ![recommended][] |              |
 | [valid-expect](docs/rules/valid-expect.md)                                   | Enforce valid `expect()` usage                                      | ![recommended][] |              |
-| [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md)             | Enforce having return statement when testing with promises          | ![recommended][] |              |
+| [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md)             | Ensure promises that have expectations in their chain are valid     | ![recommended][] |              |
 | [valid-title](docs/rules/valid-title.md)                                     | Enforce valid titles                                                | ![recommended][] | ![fixable][] |
 
 <!-- end base rules list -->

package/docs/rules/valid-expect-in-promise.md

@@ -1,31 +1,72 @@
-# Enforce having return statement when testing with promises (`valid-expect-in-promise`)
+# Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
 
-Ensure to return promise when having assertions in `then` or `catch` block of
-promise
+Ensure promises that include expectations are returned or awaited.
 
 ## Rule details
 
-This rule looks for tests that have assertions in `then` and `catch` methods on
-promises that are not returned by the test.
+This rule flags any promises within the body of a test that include expectations
+that have either not been returned or awaited.
 
-### Default configuration
-
-The following pattern is considered warning:
+The following patterns is considered warning:
 
 ```js
-it('promise test', () => {
-  somePromise.then(data => {
-    expect(data).toEqual('foo');
+it('promises a person', () => {
+  api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+});
+
+it('promises a counted person', () => {
+  const promise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+
+  promise.then(() => {
+    expect(analytics.gottenPeopleCount).toBe(1);
   });
 });
+
+it('promises multiple people', () => {
+  const firstPromise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+  const secondPromise = api.getPersonByName('alice').then(person => {
+    expect(person).toHaveProperty('name', 'Alice');
+  });
+
+  return Promise.any([firstPromise, secondPromise]);
+});
 ```
 
 The following pattern is not warning:
 
 ```js
-it('promise test', () => {
-  return somePromise.then(data => {
-    expect(data).toEqual('foo');
+it('promises a person', async () => {
+  await api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
   });
 });
+
+it('promises a counted person', () => {
+  let promise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+
+  promise = promise.then(() => {
+    expect(analytics.gottenPeopleCount).toBe(1);
+  });
+
+  return promise;
+});
+
+it('promises multiple people', () => {
+  const firstPromise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+  const secondPromise = api.getPersonByName('alice').then(person => {
+    expect(person).toHaveProperty('name', 'Alice');
+  });
+
+  return Promise.allSettled([firstPromise, secondPromise]);
+});
 ```

package/lib/rules/no-large-snapshots.js

@@ -100,8 +100,6 @@ var _default = (0, _utils.createRule)({
 
     return {
       CallExpression(node) {
-        var _matcher$node$parent;
-
         if (!(0, _utils.isExpectCall)(node)) {
           return;
         }
@@ -110,7 +108,7 @@ var _default = (0, _utils.createRule)({
           matcher
         } = (0, _utils.parseExpectCall)(node);
 
-        if ((matcher === null || matcher === void 0 ? void 0 : (_matcher$node$parent = matcher.node.parent) === null || _matcher$node$parent === void 0 ? void 0 : _matcher$node$parent.type) !== _experimentalUtils.AST_NODE_TYPES.CallExpression) {
+        if ((matcher === null || matcher === void 0 ? void 0 : matcher.node.parent.type) !== _experimentalUtils.AST_NODE_TYPES.CallExpression) {
           return;
         }
 

package/lib/rules/utils.js

@@ -233,7 +233,7 @@ const reparseAsMatcher = parsedMember => ({ ...parsedMember,
    *
    * If this matcher isn't called, this will be `null`.
    */
-  arguments: parsedMember.node.parent && parsedMember.node.parent.type === _experimentalUtils.AST_NODE_TYPES.CallExpression ? parsedMember.node.parent.arguments : null
+  arguments: parsedMember.node.parent.type === _experimentalUtils.AST_NODE_TYPES.CallExpression ? parsedMember.node.parent.arguments : null
 });
 /**
  * Re-parses the given `parsedMember` as a `ParsedExpectModifier`.
@@ -260,7 +260,7 @@ const reparseMemberAsModifier = parsedMember => {
     throw new Error(`modifier name must be either "${ModifierName.resolves}" or "${ModifierName.rejects}" (got "${parsedMember.name}")`);
   }
 
-  const negation = parsedMember.node.parent && isExpectMember(parsedMember.node.parent, ModifierName.not) ? parsedMember.node.parent : undefined;
+  const negation = isExpectMember(parsedMember.node.parent, ModifierName.not) ? parsedMember.node.parent : undefined;
   return { ...parsedMember,
     negation
   };
@@ -297,7 +297,7 @@ const parseExpectCall = expect => {
   const modifier = expectation.modifier = reparseMemberAsModifier(parsedMember);
   const memberNode = modifier.negation || modifier.node;
 
-  if (!memberNode.parent || !isExpectMember(memberNode.parent)) {
+  if (!isExpectMember(memberNode.parent)) {
     return expectation;
   }
 

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/package.json

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