feat: create new prefer-to-have-been-called-times rule

Author: G-Rath

README.md

@@ -378,6 +378,7 @@ 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-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                       |     |     |     |     |

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);
+```

src/__tests__/__snapshots__/rules.test.ts.snap

@@ -63,6 +63,7 @@ exports[`rules should export configs that refer to actual rules 1`] = `
       "jest/prefer-strict-equal": "error",
       "jest/prefer-to-be": "error",
       "jest/prefer-to-contain": "error",
+      "jest/prefer-to-have-been-called-times": "error",
       "jest/prefer-to-have-length": "error",
       "jest/prefer-todo": "error",
       "jest/require-hook": "error",
@@ -156,6 +157,7 @@ exports[`rules should export configs that refer to actual rules 1`] = `
       "jest/prefer-strict-equal": "error",
       "jest/prefer-to-be": "error",
       "jest/prefer-to-contain": "error",
+      "jest/prefer-to-have-been-called-times": "error",
       "jest/prefer-to-have-length": "error",
       "jest/prefer-todo": "error",
       "jest/require-hook": "error",

src/__tests__/rules.test.ts

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import { resolve } from 'path';
 import plugin from '../';
 
-const numberOfRules = 64;
+const numberOfRules = 65;
 const ruleNames = Object.keys(plugin.rules);
 const deprecatedRules = Object.entries(plugin.rules)
   .filter(([, rule]) => rule.meta.deprecated)

src/rules/__tests__/prefer-to-have-been-called-times.test.ts

@@ -0,0 +1,69 @@
+import rule from '../prefer-to-have-been-called-times';
+import { FlatCompatRuleTester } from './test-utils';
+
+const ruleTester = new FlatCompatRuleTester();
+
+ruleTester.run('prefer-to-have-been-called-times', rule, {
+  valid: [
+    'expect.assertions(1)',
+    'expect(fn).toHaveBeenCalledTimes',
+    'expect(fn.mock.calls).toHaveLength',
+    'expect(fn.mock.values).toHaveLength(0)',
+    'expect(fn.values.calls).toHaveLength(0)',
+    'expect(fn).toHaveBeenCalledTimes(0)',
+    'expect(fn).resolves.toHaveBeenCalledTimes(10)',
+    'expect(fn).not.toHaveBeenCalledTimes(10)',
+    'expect(fn).toHaveBeenCalledTimes(1)',
+    'expect(fn).toBeCalledTimes(0);',
+    'expect(fn).toHaveBeenCalledTimes(0);',
+    'expect(fn);',
+    'expect(method.mock.calls[0][0]).toStrictEqual(value);',
+  ],
+
+  invalid: [
+    {
+      code: 'expect(method.mock.calls).toHaveLength(1);',
+      output: 'expect(method).toHaveBeenCalledTimes(1);',
+      errors: [
+        {
+          messageId: 'preferMatcher',
+          column: 27,
+          line: 1,
+        },
+      ],
+    },
+    {
+      code: 'expect(method.mock.calls).resolves.toHaveLength(x);',
+      output: 'expect(method).resolves.toHaveBeenCalledTimes(x);',
+      errors: [
+        {
+          messageId: 'preferMatcher',
+          column: 36,
+          line: 1,
+        },
+      ],
+    },
+    {
+      code: 'expect(method["mock"].calls).toHaveLength(0);',
+      output: 'expect(method).toHaveBeenCalledTimes(0);',
+      errors: [
+        {
+          messageId: 'preferMatcher',
+          column: 30,
+          line: 1,
+        },
+      ],
+    },
+    {
+      code: 'expect(my.method.mock.calls).not.toHaveLength(0);',
+      output: 'expect(my.method).not.toHaveBeenCalledTimes(0);',
+      errors: [
+        {
+          messageId: 'preferMatcher',
+          column: 34,
+          line: 1,
+        },
+      ],
+    },
+  ],
+});

src/rules/prefer-to-have-been-called-times.ts

@@ -0,0 +1,76 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+import { createRule, isSupportedAccessor, parseJestFnCall } from './utils';
+
+export default 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 = parseJestFnCall(node, context);
+
+        if (jestFnCall?.type !== 'expect') {
+          return;
+        }
+
+        const { parent: expect } = jestFnCall.head.node;
+
+        if (expect?.type !== AST_NODE_TYPES.CallExpression) {
+          return;
+        }
+
+        const [argument] = expect.arguments;
+
+        // check if the last property in the chain is `calls`
+        if (
+          argument?.type !== AST_NODE_TYPES.MemberExpression ||
+          !isSupportedAccessor(argument.property, 'calls')
+        ) {
+          return;
+        }
+
+        const { object } = argument;
+
+        // check if the second-to-last property in the chain is `mock`
+        if (
+          object.type !== AST_NODE_TYPES.MemberExpression ||
+          !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',
+              ),
+            ];
+          },
+        });
+      },
+    };
+  },
+});