eslint-plugin-jest 24.5.0 → 24.7.0

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+# [24.7.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.6.0...v24.7.0) (2021-10-10)
+
+
+### Features
+
+* create `require-hook` rule ([#929](https://github.com/jest-community/eslint-plugin-jest/issues/929)) ([6204b31](https://github.com/jest-community/eslint-plugin-jest/commit/6204b311e849b51a0e4705015575139f590ae7a4))
+* deprecate `prefer-to-be-null` rule ([4db9161](https://github.com/jest-community/eslint-plugin-jest/commit/4db91612e988e84ac2facbfe466331b22eeccec9))
+* deprecate `prefer-to-be-undefined` rule ([fa08f09](https://github.com/jest-community/eslint-plugin-jest/commit/fa08f0944e89915fb215bbeff970f12459121cb8))
+
+# [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)
+
+
+### Bug Fixes
+
+* **lowercase-name:** consider skip and only prefixes for ignores ([#923](https://github.com/jest-community/eslint-plugin-jest/issues/923)) ([8716c24](https://github.com/jest-community/eslint-plugin-jest/commit/8716c24678ea7dc7c9f692b573d1ea19a67efd84))
+
+## [24.5.1](https://github.com/jest-community/eslint-plugin-jest/compare/v24.5.0...v24.5.1) (2021-10-04)
+
+
+### Bug Fixes
+
+* **prefer-to-be:** don't consider RegExp literals as `toBe`-able ([#922](https://github.com/jest-community/eslint-plugin-jest/issues/922)) ([99b6d42](https://github.com/jest-community/eslint-plugin-jest/commit/99b6d429e697d60645b4bc64ee4ae34d7016118c))
+
 # [24.5.0](https://github.com/jest-community/eslint-plugin-jest/compare/v24.4.3...v24.5.0) (2021-09-29)
 
 

package/README.md

@@ -184,16 +184,15 @@ installations requiring long-term consistency.
 | [prefer-spy-on](docs/rules/prefer-spy-on.md)                                 | Suggest using `jest.spyOn()`                                        |                  | ![fixable][] |
 | [prefer-strict-equal](docs/rules/prefer-strict-equal.md)                     | Suggest using `toStrictEqual()`                                     |                  | ![suggest][] |
 | [prefer-to-be](docs/rules/prefer-to-be.md)                                   | Suggest using `toBe()` for primitive literals                       |                  | ![fixable][] |
-| [prefer-to-be-null](docs/rules/prefer-to-be-null.md)                         | Suggest using `toBeNull()`                                          | ![style][]       | ![fixable][] |
-| [prefer-to-be-undefined](docs/rules/prefer-to-be-undefined.md)               | Suggest using `toBeUndefined()`                                     | ![style][]       | ![fixable][] |
 | [prefer-to-contain](docs/rules/prefer-to-contain.md)                         | Suggest using `toContain()`                                         | ![style][]       | ![fixable][] |
 | [prefer-to-have-length](docs/rules/prefer-to-have-length.md)                 | Suggest using `toHaveLength()`                                      | ![style][]       | ![fixable][] |
 | [prefer-todo](docs/rules/prefer-todo.md)                                     | Suggest using `test.todo`                                           |                  | ![fixable][] |
+| [require-hook](docs/rules/require-hook.md)                                   | Require setup and teardown code to be within a hook                 |                  |              |
 | [require-to-throw-message](docs/rules/require-to-throw-message.md)           | Require a message for `toThrow()`                                   |                  |              |
 | [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/prefer-to-be-null.md

@@ -1,5 +1,9 @@
 # Suggest using `toBeNull()` (`prefer-to-be-null`)
 
+## Deprecated
+
+This rule has been deprecated in favor of [`prefer-to-be`](prefer-to-be.md).
+
 In order to have a better failure message, `toBeNull()` should be used upon
 asserting expectations on null value.
 

package/docs/rules/prefer-to-be-undefined.md

@@ -1,5 +1,9 @@
 # Suggest using `toBeUndefined()` (`prefer-to-be-undefined`)
 
+## Deprecated
+
+This rule has been deprecated in favor of [`prefer-to-be`](prefer-to-be.md).
+
 In order to have a better failure message, `toBeUndefined()` should be used upon
 asserting expectations on undefined value.
 

package/docs/rules/require-hook.md

@@ -0,0 +1,149 @@
+# Require setup and teardown code to be within a hook (`require-hook`)
+
+Often while writing tests you have some setup work that needs to happen before
+tests run, and you have some finishing work that needs to happen after tests
+run. Jest provides helper functions to handle this.
+
+It's common when writing tests to need to perform setup work that needs to
+happen before tests run, and finishing work after tests run.
+
+Because Jest executes all `describe` handlers in a test file _before_ it
+executes any of the actual tests, it's important to ensure setup and teardown
+work is done inside `before*` and `after*` handlers respectively, rather than
+inside the `describe` blocks.
+
+## Rule details
+
+This rule flags any expression that is either at the toplevel of a test file or
+directly within the body of a `describe`, _except_ for the following:
+
+- `import` statements
+- `const` variables
+- `let` _declarations_
+- Types
+- Calls to the standard Jest globals
+
+This rule flags any function calls within test files that are directly within
+the body of a `describe`, and suggests wrapping them in one of the four
+lifecycle hooks.
+
+Here is a slightly contrived test file showcasing some common cases that would
+be flagged:
+
+```js
+import { database, isCity } from '../database';
+import { Logger } from '../../../src/Logger';
+import { loadCities } from '../api';
+
+jest.mock('../api');
+
+const initializeCityDatabase = () => {
+  database.addCity('Vienna');
+  database.addCity('San Juan');
+  database.addCity('Wellington');
+};
+
+const clearCityDatabase = () => {
+  database.clear();
+};
+
+initializeCityDatabase();
+
+test('that persists cities', () => {
+  expect(database.cities.length).toHaveLength(3);
+});
+
+test('city database has Vienna', () => {
+  expect(isCity('Vienna')).toBeTruthy();
+});
+
+test('city database has San Juan', () => {
+  expect(isCity('San Juan')).toBeTruthy();
+});
+
+describe('when loading cities from the api', () => {
+  let consoleWarnSpy = jest.spyOn(console, 'warn');
+
+  loadCities.mockResolvedValue(['Wellington', 'London']);
+
+  it('does not duplicate cities', async () => {
+    await database.loadCities();
+
+    expect(database.cities).toHaveLength(4);
+  });
+
+  it('logs any duplicates', async () => {
+    await database.loadCities();
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Ignored duplicate cities: Wellington',
+    );
+  });
+});
+
+clearCityDatabase();
+```
+
+Here is the same slightly contrived test file showcasing the same common cases
+but in ways that would be **not** flagged:
+
+```js
+import { database, isCity } from '../database';
+import { Logger } from '../../../src/Logger';
+import { loadCities } from '../api';
+
+jest.mock('../api');
+
+const initializeCityDatabase = () => {
+  database.addCity('Vienna');
+  database.addCity('San Juan');
+  database.addCity('Wellington');
+};
+
+const clearCityDatabase = () => {
+  database.clear();
+};
+
+beforeEach(() => {
+  initializeCityDatabase();
+});
+
+test('that persists cities', () => {
+  expect(database.cities.length).toHaveLength(3);
+});
+
+test('city database has Vienna', () => {
+  expect(isCity('Vienna')).toBeTruthy();
+});
+
+test('city database has San Juan', () => {
+  expect(isCity('San Juan')).toBeTruthy();
+});
+
+describe('when loading cities from the api', () => {
+  let consoleWarnSpy;
+
+  beforeEach(() => {
+    consoleWarnSpy = jest.spyOn(console, 'warn');
+    loadCities.mockResolvedValue(['Wellington', 'London']);
+  });
+
+  it('does not duplicate cities', async () => {
+    await database.loadCities();
+
+    expect(database.cities).toHaveLength(4);
+  });
+
+  it('logs any duplicates', async () => {
+    await database.loadCities();
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Ignored duplicate cities: Wellington',
+    );
+  });
+});
+
+afterEach(() => {
+  clearCityDatabase();
+});
+```

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/lowercase-name.js

@@ -21,6 +21,24 @@ const findNodeNameAndArgument = node => {
   return [(0, _utils.getNodeName)(node).split('.')[0], node.arguments[0]];
 };
 
+const populateIgnores = ignore => {
+  const ignores = [];
+
+  if (ignore.includes(_utils.DescribeAlias.describe)) {
+    ignores.push(...Object.keys(_utils.DescribeAlias));
+  }
+
+  if (ignore.includes(_utils.TestCaseName.test)) {
+    ignores.push(...Object.keys(_utils.TestCaseName));
+  }
+
+  if (ignore.includes(_utils.TestCaseName.it)) {
+    ignores.push(...Object.keys(_utils.TestCaseName));
+  }
+
+  return ignores;
+};
+
 var _default = (0, _utils.createRule)({
   name: __filename,
   meta: {
@@ -70,6 +88,7 @@ var _default = (0, _utils.createRule)({
     allowedPrefixes = [],
     ignoreTopLevelDescribe
   }]) {
+    const ignores = populateIgnores(ignore);
     let numberOfDescribeBlocks = 0;
     return {
       CallExpression(node) {
@@ -96,7 +115,7 @@ var _default = (0, _utils.createRule)({
 
         const firstCharacter = description.charAt(0);
 
-        if (!firstCharacter || firstCharacter === firstCharacter.toLowerCase() || ignore.includes(name)) {
+        if (!firstCharacter || firstCharacter === firstCharacter.toLowerCase() || ignores.includes(name)) {
           return;
         }
 

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/prefer-to-be-null.js

@@ -33,6 +33,8 @@ var _default = (0, _utils.createRule)({
     messages: {
       useToBeNull: 'Use toBeNull() instead'
     },
+    deprecated: true,
+    replacedBy: ['prefer-to-be'],
     fixable: 'code',
     type: 'suggestion',
     schema: []

package/lib/rules/prefer-to-be-undefined.js

@@ -33,6 +33,8 @@ var _default = (0, _utils.createRule)({
     messages: {
       useToBeUndefined: 'Use toBeUndefined() instead'
     },
+    deprecated: true,
+    replacedBy: ['prefer-to-be'],
     fixable: 'code',
     type: 'suggestion',
     schema: []

package/lib/rules/prefer-to-be.js

@@ -20,7 +20,10 @@ const isNullEqualityMatcher = matcher => isNullLiteral(getFirstArgument(matcher)
 
 const isFirstArgumentIdentifier = (matcher, name) => (0, _utils.isIdentifier)(getFirstArgument(matcher), name);
 
-const isPrimitiveLiteral = matcher => getFirstArgument(matcher).type === _experimentalUtils.AST_NODE_TYPES.Literal;
+const isPrimitiveLiteral = matcher => {
+  const firstArg = getFirstArgument(matcher);
+  return firstArg.type === _experimentalUtils.AST_NODE_TYPES.Literal && !('regex' in firstArg);
+};
 
 const getFirstArgument = matcher => {
   return (0, _utils.followTypeAssertionChain)(matcher.arguments[0]);

package/lib/rules/require-hook.js

@@ -0,0 +1,87 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+
+var _utils = require("./utils");
+
+const isJestFnCall = node => {
+  var _getNodeName;
+
+  if ((0, _utils.isDescribeCall)(node) || (0, _utils.isTestCaseCall)(node) || (0, _utils.isHook)(node)) {
+    return true;
+  }
+
+  return !!((_getNodeName = (0, _utils.getNodeName)(node)) !== null && _getNodeName !== void 0 && _getNodeName.startsWith('jest.'));
+};
+
+const shouldBeInHook = node => {
+  switch (node.type) {
+    case _experimentalUtils.AST_NODE_TYPES.ExpressionStatement:
+      return shouldBeInHook(node.expression);
+
+    case _experimentalUtils.AST_NODE_TYPES.CallExpression:
+      return !isJestFnCall(node);
+
+    default:
+      return false;
+  }
+};
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Require setup and teardown code to be within a hook',
+      recommended: false
+    },
+    messages: {
+      useHook: 'This should be done within a hook'
+    },
+    type: 'suggestion',
+    schema: []
+  },
+  defaultOptions: [],
+
+  create(context) {
+    const checkBlockBody = body => {
+      for (const statement of body) {
+        if (shouldBeInHook(statement)) {
+          context.report({
+            node: statement,
+            messageId: 'useHook'
+          });
+        }
+      }
+    };
+
+    return {
+      Program(program) {
+        checkBlockBody(program.body);
+      },
+
+      CallExpression(node) {
+        if (!(0, _utils.isDescribeCall)(node) || node.arguments.length < 2) {
+          return;
+        }
+
+        const [, testFn] = node.arguments;
+
+        if (!(0, _utils.isFunction)(testFn) || testFn.body.type !== _experimentalUtils.AST_NODE_TYPES.BlockStatement) {
+          return;
+        }
+
+        checkBlockBody(testFn.body.body);
+      }
+
+    };
+  }
+
+});
+
+exports.default = _default;

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.0",
+  "version": "24.7.0",
   "description": "Eslint rules for Jest",
   "keywords": [
     "eslint",