feat(eslint-plugin-jest): add prefer-called-with rule (#1025)

Author: eryue0220

internal/plugins/jest/all.go

@@ -14,6 +14,7 @@ import (
 	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/no_mocks_import"
 	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/no_standalone_expect"
 	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/no_test_prefixes"
+	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/prefer_called_with"
 	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/prefer_strict_equal"
 	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/prefer_to_be"
 	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/prefer_to_contain"
@@ -39,6 +40,7 @@ func GetAllRules() []rule.Rule {
 		no_mocks_import.NoMocksImportRule,
 		no_standalone_expect.NoStandaloneExpectRule,
 		no_test_prefixes.NoTestPrefixesRule,
+		prefer_called_with.PreferCalledWithRule,
 		prefer_strict_equal.PreferStrictEqualRule,
 		prefer_to_be.PreferToBeRule,
 		prefer_to_contain.PreferToContainRule,

internal/plugins/jest/rules/prefer_called_with/prefer_called_with.go

@@ -0,0 +1,54 @@
+package prefer_called_with
+
+import (
+	"slices"
+
+	"github.com/microsoft/typescript-go/shim/ast"
+	jestUtils "github.com/web-infra-dev/rslint/internal/plugins/jest/utils"
+	"github.com/web-infra-dev/rslint/internal/rule"
+)
+
+var preferCalledWithMatcherNames = map[string]bool{
+	"toBeCalled":       true,
+	"toHaveBeenCalled": true,
+}
+
+// Message builder
+
+func buildPreferCalledWithMessage(matcherName string) rule.RuleMessage {
+	return rule.RuleMessage{
+		Id:          "preferCalledWith",
+		Description: "Prefer " + matcherName + "With(/* expected args */)",
+		Data: map[string]string{
+			"matcherName": matcherName,
+		},
+	}
+}
+
+var PreferCalledWithRule = rule.Rule{
+	Name: "jest/prefer-called-with",
+	Run: func(ctx rule.RuleContext, options any) rule.RuleListeners {
+		return rule.RuleListeners{
+			ast.KindCallExpression: func(node *ast.Node) {
+				jestFnCall := jestUtils.ParseJestFnCall(node, ctx)
+				if jestFnCall == nil ||
+					jestFnCall.Kind != jestUtils.JestFnTypeExpect ||
+					slices.Contains(jestFnCall.Modifiers, "not") {
+					return
+				}
+
+				matcherName := jestFnCall.Matcher
+				if !preferCalledWithMatcherNames[matcherName] {
+					return
+				}
+
+				reportNode := node
+				if jestFnCall.MatcherEntry != nil && jestFnCall.MatcherEntry.Node != nil {
+					reportNode = jestFnCall.MatcherEntry.Node
+				}
+
+				ctx.ReportNode(reportNode, buildPreferCalledWithMessage(matcherName))
+			},
+		}
+	},
+}

internal/plugins/jest/rules/prefer_called_with/prefer_called_with.md

@@ -0,0 +1,37 @@
+# prefer-called-with
+
+## Rule Details
+
+The `toHaveBeenCalled()` and `toBeCalled()` matchers 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
+`toHaveBeenCalledWith()` or `toBeCalledWith()`. When some arguments are difficult
+to check, using generic matchers such as `expect.anything()` at least enforces the
+number and position of arguments.
+
+Examples of **incorrect** code for this rule:
+
+```js
+expect(someFunction).toBeCalled();
+
+expect(someFunction).toHaveBeenCalled();
+```
+
+Examples of **correct** code for this rule:
+
+```js
+expect(noArgsFunction).toHaveBeenCalledWith();
+
+expect(roughArgsFunction).toHaveBeenCalledWith(
+  expect.anything(),
+  expect.any(Date),
+);
+
+expect(anyArgsFunction).toHaveBeenCalledTimes(1);
+
+expect(uncalledFunction).not.toHaveBeenCalled();
+```
+
+## Original Documentation
+
+- [jest/prefer-called-with](https://github.com/jest-community/eslint-plugin-jest/blob/main/docs/rules/prefer-called-with.md)

internal/plugins/jest/rules/prefer_called_with/prefer_called_with_test.go

@@ -0,0 +1,53 @@
+package prefer_called_with_test
+
+import (
+	"testing"
+
+	"github.com/web-infra-dev/rslint/internal/plugins/jest/fixtures"
+	"github.com/web-infra-dev/rslint/internal/plugins/jest/rules/prefer_called_with"
+	"github.com/web-infra-dev/rslint/internal/rule_tester"
+)
+
+func TestPreferCalledWithRule(t *testing.T) {
+	rule_tester.RunRuleTester(
+		fixtures.GetRootDir(),
+		"tsconfig.json",
+		t,
+		&prefer_called_with.PreferCalledWithRule,
+		[]rule_tester.ValidTestCase{
+			{Code: `expect(fn).toBeCalledWith();`},
+			{Code: `expect(fn).toHaveBeenCalledWith();`},
+			{Code: `expect(fn).toBeCalledWith(expect.anything());`},
+			{Code: `expect(fn).toHaveBeenCalledWith(expect.anything());`},
+			{Code: `expect(fn).not.toBeCalled();`},
+			{Code: `expect(fn).rejects.not.toBeCalled();`},
+			{Code: `expect(fn).not.toHaveBeenCalled();`},
+			{Code: `expect(fn).not.toBeCalledWith();`},
+			{Code: `expect(fn).not.toHaveBeenCalledWith();`},
+			{Code: `expect(fn).resolves.not.toHaveBeenCalledWith();`},
+			{Code: `expect(fn).toBeCalledTimes(0);`},
+			{Code: `expect(fn).toHaveBeenCalledTimes(0);`},
+			{Code: `expect(fn);`},
+		},
+		[]rule_tester.InvalidTestCase{
+			{
+				Code: `expect(fn).toBeCalled();`,
+				Errors: []rule_tester.InvalidTestCaseError{
+					{MessageId: "preferCalledWith", Line: 1, Column: 12},
+				},
+			},
+			{
+				Code: `expect(fn).resolves.toBeCalled();`,
+				Errors: []rule_tester.InvalidTestCaseError{
+					{MessageId: "preferCalledWith", Line: 1, Column: 21},
+				},
+			},
+			{
+				Code: `expect(fn).toHaveBeenCalled();`,
+				Errors: []rule_tester.InvalidTestCaseError{
+					{MessageId: "preferCalledWith", Line: 1, Column: 12},
+				},
+			},
+		},
+	)
+}

packages/rslint-test-tools/rstest.config.mts

@@ -438,6 +438,7 @@ export default defineConfig({
     './tests/eslint-plugin-jest/rules/no-mocks-import.test.ts',
     './tests/eslint-plugin-jest/rules/no-standalone-expect.test.ts',
     './tests/eslint-plugin-jest/rules/no-test-prefixes.test.ts',
+    './tests/eslint-plugin-jest/rules/prefer-called-with.test.ts',
     './tests/eslint-plugin-jest/rules/prefer-strict-equal.test.ts',
     './tests/eslint-plugin-jest/rules/prefer-to-be.test.ts',
     './tests/eslint-plugin-jest/rules/prefer-to-contain.test.ts',

packages/rslint-test-tools/tests/eslint-plugin-jest/rules/prefer-called-with.test.ts

@@ -0,0 +1,56 @@
+import { RuleTester } from '../rule-tester';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run('prefer-called-with', {} as never, {
+  valid: [
+    { code: 'expect(fn).toBeCalledWith();' },
+    { code: 'expect(fn).toHaveBeenCalledWith();' },
+    { code: 'expect(fn).toBeCalledWith(expect.anything());' },
+    { code: 'expect(fn).toHaveBeenCalledWith(expect.anything());' },
+    { code: 'expect(fn).not.toBeCalled();' },
+    { code: 'expect(fn).rejects.not.toBeCalled();' },
+    { code: 'expect(fn).not.toHaveBeenCalled();' },
+    { code: 'expect(fn).not.toBeCalledWith();' },
+    { code: 'expect(fn).not.toHaveBeenCalledWith();' },
+    { code: 'expect(fn).resolves.not.toHaveBeenCalledWith();' },
+    { code: 'expect(fn).toBeCalledTimes(0);' },
+    { code: 'expect(fn).toHaveBeenCalledTimes(0);' },
+    { code: 'expect(fn);' },
+  ],
+  invalid: [
+    {
+      code: 'expect(fn).toBeCalled();',
+      errors: [
+        {
+          messageId: 'preferCalledWith',
+          data: { matcherName: 'toBeCalled' },
+          column: 12,
+          line: 1,
+        },
+      ],
+    },
+    {
+      code: 'expect(fn).resolves.toBeCalled();',
+      errors: [
+        {
+          messageId: 'preferCalledWith',
+          data: { matcherName: 'toBeCalled' },
+          column: 21,
+          line: 1,
+        },
+      ],
+    },
+    {
+      code: 'expect(fn).toHaveBeenCalled();',
+      errors: [
+        {
+          messageId: 'preferCalledWith',
+          data: { matcherName: 'toHaveBeenCalled' },
+          column: 12,
+          line: 1,
+        },
+      ],
+    },
+  ],
+});