docs: clean up expect.extend documentation (#13788)

Author: mrazauskas

docs/ExpectAPI.md

@@ -203,40 +203,7 @@ expect.extend({
 });
 ```
 
-:::note
-
-In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
-
-```ts title="toBeWithinRange.ts"
-expect.extend({
-  toBeWithinRange(received: number, floor: number, ceiling: number) {
-    // ...
-  },
-});
-declare global {
-  namespace jest {
-    interface Matchers<R> {
-      toBeWithinRange(a: number, b: number): R;
-    }
-  }
-}
-```
-
-If you want to move the typings to a separate file (e.g. `types/jest/index.d.ts`), you may need to an export, e.g.:
-
-```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 {}
-  }
-}
-export {};
-```
+:::
 
 #### Async Matchers
 

website/versioned_docs/version-28.x/ExpectAPI.md

@@ -71,8 +71,6 @@ test('numeric ranges', () => {
 
 In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
 
-:::
-
 ```ts
 expect.extend({
   toBeWithinRange(received, floor, ceiling) {
@@ -106,6 +104,8 @@ declare global {
 export {};
 ```
 
+:::
+
 #### 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.

website/versioned_docs/version-29.0/ExpectAPI.md

@@ -7,6 +7,10 @@ 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).
 
+import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md';
+
+<TypeScriptExamplesNote />
+
 ## Methods
 
 import TOCInline from '@theme/TOCInline';
@@ -37,52 +41,166 @@ 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={"span":3} title="toBeWithinRange.js"
+import {expect} from '@jest/globals';
+
+function toBeWithinRange(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,
+});
+```
+
+```js title="__tests__/ranges.test.js"
+import {expect, test} from '@jest/globals';
+import '../toBeWithinRange';
+
+test('is within range', () => expect(100).toBeWithinRange(90, 110));
+
+test('is NOT within range', () => expect(101).not.toBeWithinRange(0, 100));
+
+test('asymmetric ranges', () => {
+  expect({apples: 6, bananas: 3}).toEqual({
+    apples: expect.toBeWithinRange(1, 10),
+    bananas: expect.not.toBeWithinRange(11, 20),
+  });
+});
+```
+
+```ts title="toBeWithinRange.d.ts"
+// optionally add a type declaration, e.g. it enables autocompletion in IDEs
+declare module 'expect' {
+  interface AsymmetricMatchers {
+    toBeWithinRange(floor: number, ceiling: number): void;
+  }
+  interface Matchers<R> {
+    toBeWithinRange(floor: number, ceiling: number): R;
+  }
+}
+
+export {};
+```
+
+```ts tab={"span":2} title="toBeWithinRange.ts"
+import {expect} from '@jest/globals';
+import type {MatcherFunction} from 'expect';
+
+const toBeWithinRange: MatcherFunction<[floor: unknown, ceiling: unknown]> =
+  // `floor` and `ceiling` get types from the line above
+  // it is recommended to type them as `unknown` and to validate the values
+  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 ${received} not to be within range ${floor} - ${ceiling}`,
+          // `this` context will have correct typings
+          `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,
 });
 
-test('numeric ranges', () => {
-  expect(100).toBeWithinRange(90, 110);
-  expect(101).not.toBeWithinRange(0, 100);
+declare module 'expect' {
+  interface AsymmetricMatchers {
+    toBeWithinRange(floor: number, ceiling: number): void;
+  }
+  interface Matchers<R> {
+    toBeWithinRange(floor: number, ceiling: number): R;
+  }
+}
+```
+
+```ts tab title="__tests__/ranges.test.ts"
+import {expect, test} from '@jest/globals';
+import '../toBeWithinRange';
+
+test('is within range', () => expect(100).toBeWithinRange(90, 110));
+
+test('is NOT within range', () => expect(101).not.toBeWithinRange(0, 100));
+
+test('asymmetric ranges', () => {
   expect({apples: 6, bananas: 3}).toEqual({
     apples: expect.toBeWithinRange(1, 10),
     bananas: expect.not.toBeWithinRange(11, 20),
   });
 });
 ```
 
-:::note
+:::tip
 
-In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
+The type declaration of the matcher can live in a `.d.ts` file or in an imported `.ts` module (see JS and TS examples above respectively). If you keep the declaration in a `.d.ts` file, make sure that it is included in the program and that it is a valid module, i.e. it has at least an empty `export {}`.
 
-```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 {}
-  }
-}
+:::tip
+
+Instead of importing `toBeWithinRange` module to the test file, you can enable the matcher for all tests by moving the `expect.extend` call to a [`setupFilesAfterEnv`](Configuration.md/#setupfilesafterenv-array) script:
+
+```js
+import {expect} from '@jest/globals';
+// remember to export `toBeWithinRange` as well
+import {toBeWithinRange} from './toBeWithinRange';
+
+expect.extend({
+  toBeWithinRange,
+});
 ```
 
 :::

website/versioned_docs/version-29.1/ExpectAPI.md

@@ -203,40 +203,7 @@ expect.extend({
 });
 ```
 
-:::note
-
-In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
-
-```ts title="toBeWithinRange.ts"
-expect.extend({
-  toBeWithinRange(received: number, floor: number, ceiling: number) {
-    // ...
-  },
-});
-declare global {
-  namespace jest {
-    interface Matchers<R> {
-      toBeWithinRange(a: number, b: number): R;
-    }
-  }
-}
-```
-
-If you want to move the typings to a separate file (e.g. `types/jest/index.d.ts`), you may need to an export, e.g.:
-
-```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 {}
-  }
-}
-export {};
-```
+:::
 
 #### Async Matchers
 

website/versioned_docs/version-29.2/ExpectAPI.md

@@ -203,40 +203,7 @@ expect.extend({
 });
 ```
 
-:::note
-
-In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
-
-```ts title="toBeWithinRange.ts"
-expect.extend({
-  toBeWithinRange(received: number, floor: number, ceiling: number) {
-    // ...
-  },
-});
-declare global {
-  namespace jest {
-    interface Matchers<R> {
-      toBeWithinRange(a: number, b: number): R;
-    }
-  }
-}
-```
-
-If you want to move the typings to a separate file (e.g. `types/jest/index.d.ts`), you may need to an export, e.g.:
-
-```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 {}
-  }
-}
-export {};
-```
+:::
 
 #### Async Matchers
 

website/versioned_docs/version-29.3/ExpectAPI.md

@@ -203,40 +203,7 @@ expect.extend({
 });
 ```
 
-:::note
-
-In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
-
-```ts title="toBeWithinRange.ts"
-expect.extend({
-  toBeWithinRange(received: number, floor: number, ceiling: number) {
-    // ...
-  },
-});
-declare global {
-  namespace jest {
-    interface Matchers<R> {
-      toBeWithinRange(a: number, b: number): R;
-    }
-  }
-}
-```
-
-If you want to move the typings to a separate file (e.g. `types/jest/index.d.ts`), you may need to an export, e.g.:
-
-```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 {}
-  }
-}
-export {};
-```
+:::
 
 #### Async Matchers