docs: add few missing admonitions to the Expect API page (#13892)

Co-authored-by: Seong Min Park <psm03120@gmail.com>

docs/ExpectAPI.md

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 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 />

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

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 For additional Jest matchers maintained by the Jest Community check out [`jest-extended`](https://github.com/jest-community/jest-extended).
 
+:::
+
 ## Methods
 
 import TOCInline from '@theme/TOCInline';
@@ -67,7 +71,9 @@ test('numeric ranges', () => {
 });
 ```
 
-_Note_: In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
+:::info
+
+In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
 
 ```ts
 expect.extend({
@@ -102,6 +108,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.
@@ -807,7 +815,11 @@ test('drinkEach drinks each drink', () => {
 });
 ```
 
-Note: the nth argument must be positive integer starting from 1.
+:::note
+
+The nth argument must be positive integer starting from 1.
+
+:::
 
 ### `.toHaveReturned()`
 
@@ -906,7 +918,11 @@ test('drink returns expected nth calls', () => {
 });
 ```
 
-Note: the nth argument must be positive integer starting from 1.
+:::note
+
+The nth argument must be positive integer starting from 1.
+
+:::
 
 ### `.toHaveLength(number)`
 
@@ -1344,7 +1360,11 @@ test('throws on octopus', () => {
 });
 ```
 
-> Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
+:::tip
+
+You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
+
+:::
 
 You can provide an optional argument to test that a specific error is thrown:
 

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

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 For additional Jest matchers maintained by the Jest Community check out [`jest-extended`](https://github.com/jest-community/jest-extended).
 
+:::
+
 ## Methods
 
 import TOCInline from '@theme/TOCInline';
@@ -67,7 +71,9 @@ test('numeric ranges', () => {
 });
 ```
 
-_Note_: In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
+:::info
+
+In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
 
 ```ts
 expect.extend({
@@ -102,6 +108,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.
@@ -807,7 +815,11 @@ test('drinkEach drinks each drink', () => {
 });
 ```
 
-Note: the nth argument must be positive integer starting from 1.
+:::note
+
+The nth argument must be positive integer starting from 1.
+
+:::
 
 ### `.toHaveReturned()`
 
@@ -906,7 +918,11 @@ test('drink returns expected nth calls', () => {
 });
 ```
 
-Note: the nth argument must be positive integer starting from 1.
+:::note
+
+The nth argument must be positive integer starting from 1.
+
+:::
 
 ### `.toHaveLength(number)`
 
@@ -1344,7 +1360,11 @@ test('throws on octopus', () => {
 });
 ```
 
-> Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
+:::tip
+
+You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
+
+:::
 
 You can provide an optional argument to test that a specific error is thrown:
 

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

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 For additional Jest matchers maintained by the Jest Community check out [`jest-extended`](https://github.com/jest-community/jest-extended).
 
+:::
+
 ## Methods
 
 import TOCInline from '@theme/TOCInline';
@@ -67,9 +71,17 @@ test('numeric ranges', () => {
 });
 ```
 
-_Note_: In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
+:::info
+
+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) {
+    // ...
+  },
+});
+
 interface CustomMatchers<R = unknown> {
   toBeWithinRange(floor: number, ceiling: number): R;
 }
@@ -83,6 +95,21 @@ declare global {
 }
 ```
 
+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
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      toBeWithinRange(a: number, b: number): R;
+    }
+  }
+}
+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.
@@ -808,7 +835,11 @@ test('drinkEach drinks each drink', () => {
 });
 ```
 
-Note: the nth argument must be positive integer starting from 1.
+:::note
+
+The nth argument must be positive integer starting from 1.
+
+:::
 
 ### `.toHaveReturned()`
 
@@ -907,7 +938,11 @@ test('drink returns expected nth calls', () => {
 });
 ```
 
-Note: the nth argument must be positive integer starting from 1.
+:::note
+
+The nth argument must be positive integer starting from 1.
+
+:::
 
 ### `.toHaveLength(number)`
 
@@ -1359,7 +1394,11 @@ test('throws on octopus', () => {
 });
 ```
 
-> Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
+:::tip
+
+You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
+
+:::
 
 You can provide an optional argument to test that a specific error is thrown:
 

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

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 For additional Jest matchers maintained by the Jest Community check out [`jest-extended`](https://github.com/jest-community/jest-extended).
 
+:::
+
 ## Methods
 
 import TOCInline from '@theme/TOCInline';
@@ -67,7 +71,7 @@ test('numeric ranges', () => {
 });
 ```
 
-:::note
+:::info
 
 In TypeScript, when using `@types/jest` for example, you can declare the new `toBeWithinRange` matcher in the imported module like this:
 

website/versioned_docs/version-29.0/ExpectAPI.md

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 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 />

website/versioned_docs/version-29.1/ExpectAPI.md

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 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 />

website/versioned_docs/version-29.2/ExpectAPI.md

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 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 />

website/versioned_docs/version-29.3/ExpectAPI.md

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 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 />

website/versioned_docs/version-29.4/ExpectAPI.md

@@ -5,8 +5,12 @@ title: Expect
 
 When you're writing tests, you often need to check that values meet certain conditions. `expect` gives you access to a number of "matchers" that let you validate different things.
 
+:::tip
+
 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 />