feat(jest): allow enabling Jest global types through "types": ["jest"] in tsconfig.json

CHANGELOG.md

@@ -59,6 +59,7 @@
 ### Features
 
 - `[jest]` Expose `Config` type ([#12848](https://github.com/facebook/jest/pull/12848))
+- `[jest]` Allow enabling Jest global types through `"types": ["jest"]` in `tsconfig.json` ([#12856](https://github.com/facebook/jest/pull/12856))
 - `[@jest/reporters]` Improve `GitHubActionsReporter`s annotation format ([#12826](https://github.com/facebook/jest/pull/12826))
 - `[@jest/types]` Infer argument types passed to `test` and `describe` callback functions from `each` tables ([#12885](https://github.com/facebook/jest/pull/12885), [#12905](https://github.com/facebook/jest/pull/12905))
 

docs/ExpectAPI.md

@@ -7,6 +7,12 @@ When you're writing tests, you often need to check that values meet certain cond
 
 For additional Jest matchers maintained by the Jest Community check out [`jest-extended`](https://github.com/jest-community/jest-extended).
 
+:::info
+
+The TypeScript examples from this page assume you are using type definitions from [`jest`](GettingStarted.md/#type-definitions).
+
+:::
+
 ## Methods
 
 import TOCInline from '@theme/TOCInline';
@@ -37,56 +43,111 @@ The argument to `expect` should be the value that your code produces, and any ar
 
 You can use `expect.extend` to add your own matchers to Jest. For example, let's say that you're testing a number utility library and you're frequently asserting that numbers appear within particular ranges of other numbers. You could abstract that into a `toBeWithinRange` matcher:
 
-```js
+```js tab
+const toBeWithinRange = function (actual, floor, ceiling) {
+  if (
+    typeof actual !== 'number' ||
+    typeof floor !== 'number' ||
+    typeof ceiling !== 'number'
+  ) {
+    throw new Error('These must be of type number!');
+  }
+
+  const pass = actual >= floor && actual <= ceiling;
+  if (pass) {
+    return {
+      message: () =>
+        `expected ${this.utils.printReceived(
+          actual,
+        )} not to be within range ${this.utils.printExpected(
+          `${floor} - ${ceiling}`,
+        )}`,
+      pass: true,
+    };
+  } else {
+    return {
+      message: () =>
+        `expected ${this.utils.printReceived(
+          actual,
+        )} to be within range ${this.utils.printExpected(
+          `${floor} - ${ceiling}`,
+        )}`,
+      pass: false,
+    };
+  }
+};
+
 expect.extend({
-  toBeWithinRange(received, floor, ceiling) {
-    const pass = received >= floor && received <= ceiling;
+  toBeWithinRange,
+});
+```
+
+```ts tab
+import type {MatcherFunction} from 'expect';
+
+const toBeWithinRange: MatcherFunction<[floor: number, ceiling: number]> =
+  function (actual: unknown, floor: unknown, ceiling: unknown) {
+    if (
+      typeof actual !== 'number' ||
+      typeof floor !== 'number' ||
+      typeof ceiling !== 'number'
+    ) {
+      throw new Error('These must be of type number!');
+    }
+
+    const pass = actual >= floor && actual <= ceiling;
     if (pass) {
       return {
         message: () =>
-          `expected ${received} not to be within range ${floor} - ${ceiling}`,
+          `expected ${this.utils.printReceived(
+            actual,
+          )} not to be within range ${this.utils.printExpected(
+            `${floor} - ${ceiling}`,
+          )}`,
         pass: true,
       };
     } else {
       return {
         message: () =>
-          `expected ${received} to be within range ${floor} - ${ceiling}`,
+          `expected ${this.utils.printReceived(
+            actual,
+          )} to be within range ${this.utils.printExpected(
+            `${floor} - ${ceiling}`,
+          )}`,
         pass: false,
       };
     }
-  },
+  };
+
+expect.extend({
+  toBeWithinRange,
 });
 
+declare module 'expect' {
+  interface AsymmetricMatchers {
+    toBeWithinRange(floor: number, ceiling: number): void;
+  }
+  interface Matchers<R> {
+    toBeWithinRange(floor: number, ceiling: number): R;
+  }
+}
+```
+
+And use it in a test:
+
+```js
 test('numeric ranges', () => {
   expect(100).toBeWithinRange(90, 110);
+
   expect(101).not.toBeWithinRange(0, 100);
+
   expect({apples: 6, bananas: 3}).toEqual({
     apples: expect.toBeWithinRange(1, 10),
     bananas: expect.not.toBeWithinRange(11, 20),
   });
 });
 ```
 
-:::note
-
-In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
-
-```ts
-interface CustomMatchers<R = unknown> {
-  toBeWithinRange(floor: number, ceiling: number): R;
-}
-
-declare global {
-  namespace jest {
-    interface Expect extends CustomMatchers {}
-    interface Matchers<R> extends CustomMatchers<R> {}
-    interface InverseAsymmetricMatchers extends CustomMatchers {}
-  }
-}
-```
-
-:::
-
 #### Async Matchers
 
 `expect.extend` also supports async matchers. Async matchers return a Promise so you will need to await the returned value. Let's use an example matcher to illustrate the usage of them. We are going to implement a matcher called `toBeDivisibleByExternalValue`, where the divisible number is going to be pulled from an external source.

docs/GettingStarted.md

@@ -156,10 +156,31 @@ npm install --save-dev ts-jest
 
 #### Type definitions
 
-You may also want to install the [`@types/jest`](https://www.npmjs.com/package/@types/jest) module for the version of Jest you're using. This will help provide full typing when writing your tests with TypeScript.
+To enable type definitions of [Jest globals](GlobalAPI.md) add `"jest"` to the `"types"` list of your `tsconfig.json`:
 
-> For `@types/*` modules it's recommended to try to match the version of the associated module. For example, if you are using `26.4.0` of `jest` then using `26.4.x` of `@types/jest` is ideal. In general, try to match the major (`26`) and minor (`4`) version as closely as possible.
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "types": ["jest"]
+  }
+}
+```
 
-```bash npm2yarn
-npm install --save-dev @types/jest
+Alternatively you may use explicit imports from `@jest/globals` package:
+
+```ts title="sum.test.ts"
+import {describe, expect, test} from '@jest/globals';
+import {sum} from './sum';
+
+describe('sum module', () => {
+  test('adds 1 + 2 to equal 3', () => {
+    expect(sum(1, 2)).toBe(3);
+  });
+});
 ```
+
+:::info
+
+If you had `@types/jest` installed in your project before, remember to remove it.
+
+:::

docs/GlobalAPI.md

@@ -939,11 +939,7 @@ test.todo('add should be associative');
 
 :::info
 
-These TypeScript usage tips and caveats are only applicable if you import from `'@jest/globals'`:
-
-```ts
-import {describe, test} from '@jest/globals';
-```
+The TypeScript examples from this page assume you are using type definitions from [`jest`](GettingStarted.md/#type-definitions).
 
 :::
 

docs/MockFunctionAPI.md

@@ -7,11 +7,7 @@ Mock functions are also known as "spies", because they let you spy on the behavi
 
 :::info
 
-The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`:
-
-```ts
-import {jest} from '@jest/globals';
-```
+The TypeScript examples from this page assume you are using type definitions from [`jest`](GettingStarted.md/#type-definitions).
 
 :::
 

docs/UpgradingToJest29.md

@@ -50,9 +50,20 @@ Exports of `Mocked*` utility types from `jest-mock` package have changed. `Maybe
 
 ## TypeScript
 
+From Jest 29 you can replace `@types/jest` package with native type definitions. Simply add `"jest"` to the `"types"` list of your `tsconfig.json` and enjoy typed testing!
+
+```diff title="tsconfig.json"
+  {
+    "compilerOptions": {
+-     "types": ["@types/jest"]
++     "types": ["jest"]
+    }
+  }
+```
+
 :::info
 
-The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`:
+The TypeScript examples below assume you are using type definitions from `jest` and not `@types/jest`.
 
 ```ts
 import {jest} from '@jest/globals';

e2e/tsconfig.json

@@ -1,22 +1,8 @@
 {
+  "extends": "../tsconfig.json",
   "compilerOptions": {
-    "noEmit": true,
-
-    "target": "es2017",
-    "module": "commonjs",
-    "lib": ["dom", "es2017"],
-    "strict": true,
-
-    /* Additional Checks */
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-
-    /* Module Resolution Options */
-    "moduleResolution": "node",
-    "isolatedModules": true,
-    "importsNotUsedAsValues": "error",
-    "resolveJsonModule": true
-  }
+    "composite": false,
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
 }

examples/angular/package.json

@@ -23,7 +23,6 @@
     "@babel/plugin-proposal-decorators": "*",
     "@babel/preset-env": "^7.1.0",
     "@babel/preset-typescript": "^7.0.0",
-    "@types/jest": "^27.4.0",
     "babel-jest": "workspace:*",
     "babel-plugin-transform-typescript-metadata": "*",
     "jest": "workspace:*",

examples/expect-extend/__tests__/ranges.test.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {expect, test} from '@jest/globals';
 import '../toBeWithinRange';
 
 test('is within range', () => expect(100).toBeWithinRange(90, 110));

examples/expect-extend/toBeWithinRange.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {expect} from '@jest/globals';
 import type {MatcherFunction} from 'expect';
 
 const toBeWithinRange: MatcherFunction<[floor: number, ceiling: number]> =

examples/expect-extend/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
-    "strict": true
+    "strict": true,
+    "types": ["jest"]
   },
   "include": ["./**/*"]
 }

examples/typescript/package.json

@@ -12,7 +12,6 @@
     "@babel/preset-env": "^7.1.0",
     "@babel/preset-react": "^7.12.1",
     "@babel/preset-typescript": "^7.0.0",
-    "@types/jest": "^27.4.0",
     "babel-jest": "workspace:*",
     "jest": "workspace:*"
   },

examples/typescript/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "module": "commonjs",
-    "jsx": "react-jsx"
+    "jsx": "react-jsx",
+    "types": ["jest"]
   }
 }

package.json

@@ -20,7 +20,6 @@
     "@types/babel__generator": "^7.0.0",
     "@types/babel__template": "^7.0.2",
     "@types/dedent": "^0.7.0",
-    "@types/jest": "^27.4.0",
     "@types/node": "~14.14.45",
     "@types/which": "^2.0.0",
     "@typescript-eslint/eslint-plugin": "^5.14.0",

packages/babel-jest/src/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "esModuleInterop": true,
+    "rootDir": "../",
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
+}

packages/babel-plugin-jest-hoist/src/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "esModuleInterop": true,
+    "rootDir": "../",
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
+}

packages/diff-sequences/src/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "esModuleInterop": true,
+    "rootDir": "../",
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
+}

packages/expect-utils/src/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "esModuleInterop": true,
+    "rootDir": "../",
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
+}

packages/expect/src/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "esModuleInterop": true,
+    "rootDir": "../",
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
+}

packages/jest-circus/src/__tests__/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "composite": false,
+    "esModuleInterop": true,
+    "rootDir": "../",
+    "types": ["jest"]
+  },
+  "include": ["../**/*"]
+}