CHANGELOG.md

@@ -1,3 +1,10 @@
+# [28.1.0](https://github.com/jest-community/eslint-plugin-jest/compare/v28.0.0...v28.1.0) (2024-04-06)
+
+
+### Features
+
+* add `prefer-importing-jest-globals` rule ([#1490](https://github.com/jest-community/eslint-plugin-jest/issues/1490)) ([37478d8](https://github.com/jest-community/eslint-plugin-jest/commit/37478d860eb15841f2ab73bb3fb6d94f51841638)), closes [#1101](https://github.com/jest-community/eslint-plugin-jest/issues/1101)
+
 # [28.0.0](https://github.com/jest-community/eslint-plugin-jest/compare/v27.9.0...v28.0.0) (2024-04-06)
 
 

README.md

@@ -328,6 +328,7 @@ set to warn in.\
 | [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md)               | Prefer `await expect(...).resolves` over `expect(await ...)` syntax       |     |     | 🔧  |     |
 | [prefer-hooks-in-order](docs/rules/prefer-hooks-in-order.md)                 | Prefer having hooks in a consistent order                                 |     |     |     |     |
 | [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)                     | Suggest having hooks before any test cases                                |     |     |     |     |
+| [prefer-importing-jest-globals](docs/rules/prefer-importing-jest-globals.md) | Prefer importing Jest globals                                             |     |     | 🔧  |     |
 | [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md)               | Enforce lowercase test names                                              |     |     | 🔧  |     |
 | [prefer-mock-promise-shorthand](docs/rules/prefer-mock-promise-shorthand.md) | Prefer mock resolved/rejected shorthands for promises                     |     |     | 🔧  |     |
 | [prefer-snapshot-hint](docs/rules/prefer-snapshot-hint.md)                   | Prefer including a hint with external snapshots                           |     |     |     |     |

docs/rules/prefer-importing-jest-globals.md

@@ -0,0 +1,47 @@
+# Prefer importing Jest globals (`prefer-importing-jest-globals`)
+
+🔧 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 -->
+
+This rule aims to enforce explicit imports from `@jest/globals`.
+
+1. This is useful for ensuring that the Jest APIs are imported the same way in
+   the codebase.
+2. When you can't modify Jest's
+   [`injectGlobals`](https://jestjs.io/docs/configuration#injectglobals-boolean)
+   configuration property, this rule can help to ensure that the Jest globals
+   are imported explicitly and facilitate a migration to `@jest/globals`.
+
+## Rule details
+
+Examples of **incorrect** code for this rule
+
+```js
+/* eslint jest/prefer-importing-jest-globals: "error" */
+
+describe('foo', () => {
+  it('accepts this input', () => {
+    // ...
+  });
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+/* eslint jest/prefer-importing-jest-globals: "error" */
+
+import { describe, it } from '@jest/globals';
+
+describe('foo', () => {
+  it('accepts this input', () => {
+    // ...
+  });
+});
+```
+
+## Further Reading
+
+- [Documentation](https://jestjs.io/docs/api)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "28.0.0",
+  "version": "28.1.0",
   "description": "ESLint rules for Jest",
   "keywords": [
     "eslint",
@@ -130,8 +130,5 @@
   },
   "publishConfig": {
     "provenance": true
-  },
-  "resolutions": {
-    "@typescript-eslint/typescript-estree@5.62.0": "patch:@typescript-eslint/typescript-estree@npm:^5.62.0#./.yarn/patches/@typescript-eslint-typescript-estree-npm-5.62.0-5d1ea132a9.patch"
   }
 }

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

@@ -45,6 +45,7 @@ exports[`rules should export configs that refer to actual rules 1`] = `
       "jest/prefer-expect-resolves": "error",
       "jest/prefer-hooks-in-order": "error",
       "jest/prefer-hooks-on-top": "error",
+      "jest/prefer-importing-jest-globals": "error",
       "jest/prefer-lowercase-title": "error",
       "jest/prefer-mock-promise-shorthand": "error",
       "jest/prefer-snapshot-hint": "error",
@@ -126,6 +127,7 @@ exports[`rules should export configs that refer to actual rules 1`] = `
       "jest/prefer-expect-resolves": "error",
       "jest/prefer-hooks-in-order": "error",
       "jest/prefer-hooks-on-top": "error",
+      "jest/prefer-importing-jest-globals": "error",
       "jest/prefer-lowercase-title": "error",
       "jest/prefer-mock-promise-shorthand": "error",
       "jest/prefer-snapshot-hint": "error",

src/__tests__/rules.test.ts

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

src/rules/prefer-importing-jest-globals.ts

@@ -0,0 +1,163 @@
+import { AST_NODE_TYPES, type TSESTree } from '@typescript-eslint/utils';
+import {
+  createRule,
+  getAccessorValue,
+  getSourceCode,
+  isIdentifier,
+  isStringNode,
+  isSupportedAccessor,
+  parseJestFnCall,
+} from './utils';
+
+const createFixerImports = (
+  isModule: boolean,
+  functionsToImport: Set<string>,
+) => {
+  const allImportsFormatted = Array.from(functionsToImport).sort().join(', ');
+
+  return isModule
+    ? `import { ${allImportsFormatted} } from '@jest/globals';`
+    : `const { ${allImportsFormatted} } = require('@jest/globals');`;
+};
+
+export default createRule({
+  name: __filename,
+  meta: {
+    docs: {
+      description: 'Prefer importing Jest globals',
+    },
+    messages: {
+      preferImportingJestGlobal: `Import the following Jest functions from '@jest/globals': {{ jestFunctions }}`,
+    },
+    fixable: 'code',
+    type: 'problem',
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    const importedFunctionsWithSource: Record<string, string> = {};
+    const functionsToImport = new Set<string>();
+    let reportingNode: TSESTree.Node;
+
+    return {
+      ImportDeclaration(node: TSESTree.ImportDeclaration) {
+        node.specifiers.forEach(specifier => {
+          if (specifier.type === 'ImportSpecifier') {
+            importedFunctionsWithSource[specifier.local.name] =
+              node.source.value;
+          }
+        });
+      },
+      CallExpression(node: TSESTree.CallExpression) {
+        const jestFnCall = parseJestFnCall(node, context);
+
+        if (!jestFnCall) {
+          return;
+        }
+
+        if (jestFnCall.head.type !== 'import') {
+          functionsToImport.add(jestFnCall.name);
+          reportingNode ||= jestFnCall.head.node;
+        }
+      },
+      'Program:exit'() {
+        // this means we found at least one function to import
+        if (!reportingNode) {
+          return;
+        }
+
+        const isModule = context.parserOptions.sourceType === 'module';
+
+        context.report({
+          node: reportingNode,
+          messageId: 'preferImportingJestGlobal',
+          data: { jestFunctions: Array.from(functionsToImport).join(', ') },
+          fix(fixer) {
+            const sourceCode = getSourceCode(context);
+            const [firstNode] = sourceCode.ast.body;
+
+            // check if "use strict" directive exists
+            if (
+              firstNode.type === AST_NODE_TYPES.ExpressionStatement &&
+              isStringNode(firstNode.expression, 'use strict')
+            ) {
+              return fixer.insertTextAfter(
+                firstNode,
+                `\n${createFixerImports(isModule, functionsToImport)}`,
+              );
+            }
+
+            const importNode = sourceCode.ast.body.find(
+              node =>
+                node.type === AST_NODE_TYPES.ImportDeclaration &&
+                node.source.value === '@jest/globals',
+            );
+
+            if (importNode?.type === AST_NODE_TYPES.ImportDeclaration) {
+              for (const specifier of importNode.specifiers) {
+                if (
+                  specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+                  specifier.imported?.name
+                ) {
+                  functionsToImport.add(specifier.imported.name);
+                }
+
+                if (specifier.type === AST_NODE_TYPES.ImportDefaultSpecifier) {
+                  functionsToImport.add(specifier.local.name);
+                }
+              }
+
+              return fixer.replaceText(
+                importNode,
+                createFixerImports(isModule, functionsToImport),
+              );
+            }
+
+            const requireNode = sourceCode.ast.body.find(
+              node =>
+                node.type === AST_NODE_TYPES.VariableDeclaration &&
+                node.declarations.some(
+                  declaration =>
+                    declaration.init?.type === AST_NODE_TYPES.CallExpression &&
+                    isIdentifier(declaration.init.callee, 'require') &&
+                    isStringNode(
+                      declaration.init.arguments[0],
+                      '@jest/globals',
+                    ) &&
+                    (declaration.id.type === AST_NODE_TYPES.Identifier ||
+                      declaration.id.type === AST_NODE_TYPES.ObjectPattern),
+                ),
+            );
+
+            if (requireNode?.type !== AST_NODE_TYPES.VariableDeclaration) {
+              return fixer.insertTextBefore(
+                reportingNode,
+                `${createFixerImports(isModule, functionsToImport)}\n`,
+              );
+            }
+
+            if (
+              requireNode.declarations[0]?.id.type ===
+              AST_NODE_TYPES.ObjectPattern
+            ) {
+              for (const property of requireNode.declarations[0].id
+                .properties) {
+                if (
+                  property.type === AST_NODE_TYPES.Property &&
+                  isSupportedAccessor(property.key)
+                ) {
+                  functionsToImport.add(getAccessorValue(property.key));
+                }
+              }
+            }
+
+            return fixer.replaceText(
+              requireNode,
+              `${createFixerImports(isModule, functionsToImport)}`,
+            );
+          },
+        });
+      },
+    };
+  },
+});

yarn.lock

@@ -3054,26 +3054,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@typescript-eslint/typescript-estree@npm:6.21.0":
-  version: 6.21.0
-  resolution: "@typescript-eslint/typescript-estree@npm:6.21.0"
-  dependencies:
-    "@typescript-eslint/types": 6.21.0
-    "@typescript-eslint/visitor-keys": 6.21.0
-    debug: ^4.3.4
-    globby: ^11.1.0
-    is-glob: ^4.0.3
-    minimatch: 9.0.3
-    semver: ^7.5.4
-    ts-api-utils: ^1.0.1
-  peerDependenciesMeta:
-    typescript:
-      optional: true
-  checksum: dec02dc107c4a541e14fb0c96148f3764b92117c3b635db3a577b5a56fc48df7a556fa853fb82b07c0663b4bf2c484c9f245c28ba3e17e5cb0918ea4cab2ea21
-  languageName: node
-  linkType: hard
-
-"@typescript-eslint/typescript-estree@npm:^5.62.0":
+"@typescript-eslint/typescript-estree@npm:5.62.0":
   version: 5.62.0
   resolution: "@typescript-eslint/typescript-estree@npm:5.62.0"
   dependencies:
@@ -3091,21 +3072,22 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@typescript-eslint/typescript-estree@patch:@typescript-eslint/typescript-estree@npm:^5.62.0#./.yarn/patches/@typescript-eslint-typescript-estree-npm-5.62.0-5d1ea132a9.patch::locator=eslint-plugin-jest%40workspace%3A.":
-  version: 5.62.0
-  resolution: "@typescript-eslint/typescript-estree@patch:@typescript-eslint/typescript-estree@npm%3A5.62.0#./.yarn/patches/@typescript-eslint-typescript-estree-npm-5.62.0-5d1ea132a9.patch::version=5.62.0&hash=bbaf25&locator=eslint-plugin-jest%40workspace%3A."
+"@typescript-eslint/typescript-estree@npm:6.21.0":
+  version: 6.21.0
+  resolution: "@typescript-eslint/typescript-estree@npm:6.21.0"
   dependencies:
-    "@typescript-eslint/types": 5.62.0
-    "@typescript-eslint/visitor-keys": 5.62.0
+    "@typescript-eslint/types": 6.21.0
+    "@typescript-eslint/visitor-keys": 6.21.0
     debug: ^4.3.4
     globby: ^11.1.0
     is-glob: ^4.0.3
-    semver: ^7.3.7
-    tsutils: ^3.21.0
+    minimatch: 9.0.3
+    semver: ^7.5.4
+    ts-api-utils: ^1.0.1
   peerDependenciesMeta:
     typescript:
       optional: true
-  checksum: 166673643210b8786c3190b3261c22e1b67025489f579183e1cb6cb58a80ea0dd2e12c98aec86ad557b852fb9fd5ae1dc9c913bccdb96a57459228af7adb0c63
+  checksum: dec02dc107c4a541e14fb0c96148f3764b92117c3b635db3a577b5a56fc48df7a556fa853fb82b07c0663b4bf2c484c9f245c28ba3e17e5cb0918ea4cab2ea21
   languageName: node
   linkType: hard