eslint-plugin-jest 29.2.3 → 29.4.0

package/README.md

@@ -360,7 +360,7 @@ Manually fixable by
 | [padding-around-describe-blocks](docs/rules/padding-around-describe-blocks.md)       | Enforce padding around `describe` blocks                                  |     |     | 🔧  |     |
 | [padding-around-expect-groups](docs/rules/padding-around-expect-groups.md)           | Enforce padding around `expect` groups                                    |     |     | 🔧  |     |
 | [padding-around-test-blocks](docs/rules/padding-around-test-blocks.md)               | Enforce padding around `test` and `it` blocks                             |     |     | 🔧  |     |
-| [prefer-called-with](docs/rules/prefer-called-with.md)                               | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`              |     |     |     |     |
+| [prefer-called-with](docs/rules/prefer-called-with.md)                               | Suggest using `toHaveBeenCalledWith()`                                    |     |     |     |     |
 | [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md)                 | Suggest using the built-in comparison matchers                            |     |     | 🔧  |     |
 | [prefer-each](docs/rules/prefer-each.md)                                             | Prefer using `.each` rather than manual loops                             |     |     |     |     |
 | [prefer-ending-with-an-expect](docs/rules/prefer-ending-with-an-expect.md)           | Prefer having the last statement in a test be an assertion                |     |     |     |     |
@@ -378,6 +378,8 @@ Manually fixable by
 | [prefer-strict-equal](docs/rules/prefer-strict-equal.md)                             | Suggest using `toStrictEqual()`                                           |     |     |     | 💡  |
 | [prefer-to-be](docs/rules/prefer-to-be.md)                                           | Suggest using `toBe()` for primitive literals                             | 🎨  |     | 🔧  |     |
 | [prefer-to-contain](docs/rules/prefer-to-contain.md)                                 | Suggest using `toContain()`                                               | 🎨  |     | 🔧  |     |
+| [prefer-to-have-been-called](docs/rules/prefer-to-have-been-called.md)               | Suggest using `toHaveBeenCalled`                                          |     |     | 🔧  |     |
+| [prefer-to-have-been-called-times](docs/rules/prefer-to-have-been-called-times.md)   | Suggest using `toHaveBeenCalledTimes()`                                   |     |     | 🔧  |     |
 | [prefer-to-have-length](docs/rules/prefer-to-have-length.md)                         | Suggest using `toHaveLength()`                                            | 🎨  |     | 🔧  |     |
 | [prefer-todo](docs/rules/prefer-todo.md)                                             | Suggest using `test.todo`                                                 |     |     | 🔧  |     |
 | [require-hook](docs/rules/require-hook.md)                                           | Require setup and teardown code to be within a hook                       |     |     |     |     |

package/docs/rules/prefer-called-with.md

@@ -1,10 +1,10 @@
-# Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
+# Suggest using `toHaveBeenCalledWith()` (`prefer-called-with`)
 
 <!-- end auto-generated rule header -->
 
-The `toBeCalled()` matcher is used to assert that a mock function has been
+The `toHaveBeenCalled()` matcher is used to assert that a mock function has been
 called one or more times, without checking the arguments passed. The assertion
-is stronger when arguments are also validated using the `toBeCalledWith()`
+is stronger when arguments are also validated using the `toHaveBeenCalledWith()`
 matcher. When some arguments are difficult to check, using generic match like
 `expect.anything()` at least enforces number and position of arguments.
 
@@ -24,11 +24,14 @@ expect(someFunction).toHaveBeenCalled();
 The following patterns are not warnings:
 
 ```js
-expect(noArgsFunction).toBeCalledWith();
+expect(noArgsFunction).toHaveBeenCalledWith();
 
-expect(roughArgsFunction).toBeCalledWith(expect.anything(), expect.any(Date));
+expect(roughArgsFunction).toHaveBeenCalledWith(
+  expect.anything(),
+  expect.any(Date),
+);
 
-expect(anyArgsFunction).toBeCalledTimes(1);
+expect(anyArgsFunction).toHaveBeenCalledTimes(1);
 
-expect(uncalledFunction).not.toBeCalled();
+expect(uncalledFunction).not.toHaveBeenCalled();
 ```

package/docs/rules/prefer-to-have-been-called-times.md

@@ -0,0 +1,41 @@
+# Suggest using `toHaveBeenCalledTimes()` (`prefer-to-have-been-called-times`)
+
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+In order to have a better failure message, `toHaveBeenCalledTimes` should be
+used instead of directly checking the length of `mock.calls`.
+
+## Rule details
+
+This rule triggers a warning if `toHaveLength` is used to assert the number of
+times a mock is called.
+
+> [!NOTE]
+>
+> This rule should ideally be paired with
+> [`prefer-to-have-length`](./prefer-to-have-length.md)
+
+The following patterns are considered warnings:
+
+```js
+expect(someFunction.mock.calls).toHaveLength(1);
+expect(someFunction.mock.calls).toHaveLength(0);
+
+expect(someFunction.mock.calls).not.toHaveLength(1);
+```
+
+The following patterns are not warnings:
+
+```js
+expect(someFunction).toHaveBeenCalledTimes(1);
+expect(someFunction).toHaveBeenCalledTimes(0);
+
+expect(someFunction).not.toHaveBeenCalledTimes(0);
+
+expect(uncalledFunction).not.toBeCalled();
+
+expect(method.mock.calls[0][0]).toStrictEqual(value);
+```

package/docs/rules/prefer-to-have-been-called.md

@@ -0,0 +1,33 @@
+# Suggest using `toHaveBeenCalled` (`prefer-to-have-been-called`)
+
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+In order to have a better failure message, `toHaveBeenCalled` should be used
+instead of checking the number of times a mock has been called.
+
+## Rule details
+
+This rule triggers a warning if `toHaveBeenCalledTimes` is used to assert that a
+mock has or has not been called zero times
+
+> [!NOTE]
+>
+> This rule should ideally be paired with
+> [`prefer-to-have-been-called-times`](./prefer-to-have-been-called-times.md)
+
+The following patterns are considered warnings:
+
+```js
+expect(someFunction).toHaveBeenCalledTimes(0);
+expect(someFunction).not.toHaveBeenCalledTimes(0);
+```
+
+The following patterns are not warnings:
+
+```js
+expect(someFunction).not.toHaveBeenCalled();
+expect(someFunction).toHaveBeenCalled();
+```

package/lib/rules/prefer-called-with.js

@@ -9,7 +9,7 @@ var _default = exports.default = (0, _utils.createRule)({
   name: __filename,
   meta: {
     docs: {
-      description: 'Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`'
+      description: 'Suggest using `toHaveBeenCalledWith()`'
     },
     messages: {
       preferCalledWith: 'Prefer {{ matcherName }}With(/* expected args */)'

package/lib/rules/prefer-expect-assertions.js

@@ -68,6 +68,7 @@ var _default = exports.default = (0, _utils2.createRule)({
   }],
   create(context, [options]) {
     let expressionDepth = 0;
+    let describeDepth = 0;
     let hasExpectInCallback = false;
     let hasExpectInLoop = false;
     let hasExpectAssertionsAsFirstStatement = false;
@@ -134,6 +135,14 @@ var _default = exports.default = (0, _utils2.createRule)({
     const exitExpression = () => inTestCaseCall && expressionDepth--;
     const enterForLoop = () => inForLoop = true;
     const exitForLoop = () => inForLoop = false;
+    let inEachHook = false;
+
+    // when set to a non-negative value, all expect calls within describes whose depth
+    // are equal to or higher than this value are covered by an expect.hasAssertions set
+    // up within a beforeEach or afterEach hook
+    //
+    // when the describe depth is lower than the current value, it gets reset to -1
+    let coveredByHookAtDepth = -1;
     return {
       FunctionExpression: enterExpression,
       'FunctionExpression:exit': exitExpression,
@@ -147,10 +156,22 @@ var _default = exports.default = (0, _utils2.createRule)({
       'ForOfStatement:exit': exitForLoop,
       CallExpression(node) {
         const jestFnCall = (0, _utils2.parseJestFnCall)(node, context);
+        if (jestFnCall?.type === 'describe') {
+          describeDepth += 1;
+        }
+        if (jestFnCall?.type === 'hook' && jestFnCall.name.endsWith('Each')) {
+          inEachHook = true;
+        }
         if (jestFnCall?.type === 'test') {
           inTestCaseCall = true;
           return;
         }
+        if (jestFnCall?.type === 'expect' && inEachHook && (0, _utils2.getAccessorValue)(jestFnCall.members[0]) === 'hasAssertions') {
+          checkExpectHasAssertions(jestFnCall, node);
+          if (coveredByHookAtDepth < 0) {
+            coveredByHookAtDepth = describeDepth;
+          }
+        }
         if (jestFnCall?.type === 'expect' && inTestCaseCall) {
           if (expressionDepth === 1 && isFirstStatement(node) && ['assertions', 'hasAssertions'].includes((0, _utils2.getAccessorValue)(jestFnCall.members[0]))) {
             checkExpectHasAssertions(jestFnCall, node);
@@ -165,7 +186,20 @@ var _default = exports.default = (0, _utils2.createRule)({
         }
       },
       'CallExpression:exit'(node) {
-        if (!(0, _utils2.isTypeOfJestFnCall)(node, context, ['test'])) {
+        const jestFnCall = (0, _utils2.parseJestFnCall)(node, context);
+        if (jestFnCall?.type === 'describe') {
+          describeDepth -= 1;
+
+          // clear the "covered by each hook" flag if we have left the describe
+          // depth that it applies to
+          if (coveredByHookAtDepth > describeDepth) {
+            coveredByHookAtDepth = -1;
+          }
+        }
+        if (jestFnCall?.type === 'hook' && jestFnCall.name.endsWith('Each')) {
+          inEachHook = false;
+        }
+        if (jestFnCall?.type !== 'test') {
           return;
         }
         inTestCaseCall = false;
@@ -182,6 +216,9 @@ var _default = exports.default = (0, _utils2.createRule)({
           hasExpectAssertionsAsFirstStatement = false;
           return;
         }
+        if (coveredByHookAtDepth >= 0 && coveredByHookAtDepth <= describeDepth) {
+          return;
+        }
         const suggestions = [];
         if (testFn.body.type === _utils.AST_NODE_TYPES.BlockStatement) {
           suggestions.push(['suggestAddingHasAssertions', 'expect.hasAssertions();'], ['suggestAddingAssertions', 'expect.assertions();']);

package/lib/rules/prefer-to-have-been-called-times.js

@@ -0,0 +1,67 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("@typescript-eslint/utils");
+var _utils2 = require("./utils");
+var _default = exports.default = (0, _utils2.createRule)({
+  name: __filename,
+  meta: {
+    fixable: 'code',
+    docs: {
+      description: 'Suggest using `toHaveBeenCalledTimes()`'
+    },
+    messages: {
+      preferMatcher: 'Prefer `toHaveBeenCalledTimes`'
+    },
+    type: 'suggestion',
+    schema: []
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        const jestFnCall = (0, _utils2.parseJestFnCall)(node, context);
+        if (jestFnCall?.type !== 'expect') {
+          return;
+        }
+        const {
+          parent: expect
+        } = jestFnCall.head.node;
+        if (expect?.type !== _utils.AST_NODE_TYPES.CallExpression) {
+          return;
+        }
+        const [argument] = expect.arguments;
+
+        // check if the last property in the chain is `calls`
+        if (argument?.type !== _utils.AST_NODE_TYPES.MemberExpression || !(0, _utils2.isSupportedAccessor)(argument.property, 'calls')) {
+          return;
+        }
+        const {
+          object
+        } = argument;
+
+        // check if the second-to-last property in the chain is `mock`
+        if (object.type !== _utils.AST_NODE_TYPES.MemberExpression || !(0, _utils2.isSupportedAccessor)(object.property, 'mock')) {
+          return;
+        }
+        const {
+          matcher
+        } = jestFnCall;
+        context.report({
+          messageId: 'preferMatcher',
+          node: matcher,
+          fix(fixer) {
+            return [
+            // remove the "mock.calls" accessor chain
+            fixer.removeRange([object.property.range[0] - 1, argument.range[1]]),
+            // replace the current matcher with "toHaveBeenCalledTimes"
+            fixer.replaceTextRange([matcher.parent.object.range[1], matcher.parent.range[1]], '.toHaveBeenCalledTimes')];
+          }
+        });
+      }
+    };
+  }
+});

package/lib/rules/prefer-to-have-been-called.js

@@ -0,0 +1,59 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _utils = require("@typescript-eslint/utils");
+var _utils2 = require("./utils");
+var _default = exports.default = (0, _utils2.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      description: 'Suggest using `toHaveBeenCalled`'
+    },
+    messages: {
+      preferMatcher: 'Use `toHaveBeenCalled`'
+    },
+    fixable: 'code',
+    type: 'suggestion',
+    schema: []
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      CallExpression(node) {
+        const jestFnCall = (0, _utils2.parseJestFnCall)(node, context);
+        if (jestFnCall?.type !== 'expect') {
+          return;
+        }
+        const {
+          matcher
+        } = jestFnCall;
+        if (!['toBeCalledTimes', 'toHaveBeenCalledTimes'].includes((0, _utils2.getAccessorValue)(matcher))) {
+          return;
+        }
+        const arg = (0, _utils2.getFirstMatcherArg)(jestFnCall);
+        if (arg.type !== _utils.AST_NODE_TYPES.Literal || arg.value !== 0) {
+          return;
+        }
+        const notModifier = jestFnCall.modifiers.find(nod => (0, _utils2.getAccessorValue)(nod) === 'not');
+        context.report({
+          messageId: 'preferMatcher',
+          node: matcher,
+          fix(fixer) {
+            let replacementMatcher = '.not.toHaveBeenCalled';
+            if (notModifier) {
+              replacementMatcher = '.toHaveBeenCalled';
+            }
+            return [
+            // remove all the arguments to the matcher
+            fixer.removeRange([jestFnCall.args[0].range[0], jestFnCall.args[jestFnCall.args.length - 1].range[1]]),
+            // replace the current matcher with "(.not).toHaveBeenCalled"
+            fixer.replaceTextRange([(notModifier || matcher).parent.object.range[1], jestFnCall.matcher.parent.range[1]], replacementMatcher)];
+          }
+        });
+      }
+    };
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "29.2.3",
+  "version": "29.4.0",
   "description": "ESLint rules for Jest",
   "keywords": [
     "eslint",