From 396b3fafb3cad171fbe8af3bff8dbc1b383b7755 Mon Sep 17 00:00:00 2001 From: Tom Mrazauskas Date: Tue, 6 Sep 2022 01:09:13 +0300 Subject: [PATCH] docs: use TypeScript Examples Note partial (#13212) --- docs/ExpectAPI.md | 10 ++----- docs/GlobalAPI.md | 26 ++++++++++++------- docs/JestObjectAPI.md | 10 ++----- docs/MockFunctionAPI.md | 10 ++----- docs/UpgradingToJest29.md | 10 ++----- docs/_TypeScriptExamplesNote.md | 9 +++++++ .../version-28.x/MockFunctionAPI.md | 10 ++----- .../version-28.x/UpgradingToJest28.md | 10 ++----- .../version-28.x/_TypeScriptExamplesNote.md | 9 +++++++ .../versioned_docs/version-29.0/GlobalAPI.md | 26 ++++++++++++------- .../version-29.0/JestObjectAPI.md | 4 +++ .../version-29.0/MockFunctionAPI.md | 10 ++----- .../version-29.0/UpgradingToJest29.md | 10 ++----- .../version-29.0/_TypeScriptExamplesNote.md | 9 +++++++ 14 files changed, 79 insertions(+), 84 deletions(-) create mode 100644 docs/_TypeScriptExamplesNote.md create mode 100644 website/versioned_docs/version-28.x/_TypeScriptExamplesNote.md create mode 100644 website/versioned_docs/version-29.0/_TypeScriptExamplesNote.md diff --git a/docs/ExpectAPI.md b/docs/ExpectAPI.md index 34291ecbec20..f261e3c4bb0f 100644 --- a/docs/ExpectAPI.md +++ b/docs/ExpectAPI.md @@ -7,15 +7,9 @@ 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 +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -The TypeScript examples from this page will only work as documented if you import `expect` from `'@jest/globals'`: - -```ts -import {expect} from '@jest/globals'; -``` - -::: + ## Methods diff --git a/docs/GlobalAPI.md b/docs/GlobalAPI.md index f41f1eedcbc4..775d40d11d9c 100644 --- a/docs/GlobalAPI.md +++ b/docs/GlobalAPI.md @@ -5,6 +5,10 @@ title: Globals In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them. However, if you prefer explicit imports, you can do `import {describe, expect, test} from '@jest/globals'`. +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; + + + ## Methods import TOCInline from '@theme/TOCInline'; @@ -969,16 +973,6 @@ test.todo('add should be associative'); ## TypeScript Usage -:::info - -These TypeScript usage tips and caveats are only applicable if you import from `'@jest/globals'`: - -```ts -import {describe, test} from '@jest/globals'; -``` - -::: - ### `.each` The `.each` modifier offers few different ways to define a table of the test cases. Some of the APIs have caveats related with the type inference of the arguments which are passed to `describe` or `test` callback functions. Let's take a look at each of them. @@ -994,6 +988,8 @@ For simplicity `test.each` is picked for the examples, but the type inference is The array of objects API is most verbose, but it makes the type inference a painless task. A `table` can be inlined: ```ts +import {test} from '@jest/globals'; + test.each([ {name: 'a', path: 'path/to/a', count: 1, write: true}, {name: 'b', path: 'path/to/b', count: 3}, @@ -1005,6 +1001,8 @@ test.each([ Or declared separately as a variable: ```ts +import {test} from '@jest/globals'; + const table = [ {a: 1, b: 2, expected: 'three', extra: true}, {a: 3, b: 4, expected: 'seven', extra: false}, @@ -1021,6 +1019,8 @@ test.each(table)('table as a variable', ({a, b, expected, extra}) => { The array of arrays style will work smoothly with inlined tables: ```ts +import {test} from '@jest/globals'; + test.each([ [1, 2, 'three', true], [3, 4, 'seven', false], @@ -1033,6 +1033,8 @@ test.each([ However, if a table is declared as a separate variable, it must be typed as an array of tuples for correct type inference (this is not needed only if all elements of a row are of the same type): ```ts +import {test} from '@jest/globals'; + const table: Array<[number, number, string, boolean?]> = [ [1, 2, 'three', true], [3, 4, 'seven', false], @@ -1049,6 +1051,8 @@ test.each(table)('table as a variable example', (a, b, expected, extra) => { If all values are of the same type, the template literal API will type the arguments correctly: ```ts +import {test} from '@jest/globals'; + test.each` a | b | expected ${1} | ${2} | ${3} @@ -1062,6 +1066,8 @@ test.each` Otherwise it will require a generic type argument: ```ts +import {test} from '@jest/globals'; + test.each<{a: number; b: number; expected: string; extra?: boolean}>` a | b | expected | extra ${1} | ${2} | ${'three'} | ${true} diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index b80a1759e1b1..8fcc8f2048fb 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -5,15 +5,9 @@ title: The Jest Object The `jest` object is automatically in scope within every test file. The methods in the `jest` object help create mocks and let you control Jest's overall behavior. It can also be imported explicitly by via `import {jest} from '@jest/globals'`. -:::info - -The TypeScript examples from this page will only work as documented if you import global APIs from `'@jest/globals'`: - -```ts -import {expect, jest, test} from '@jest/globals'; -``` +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -::: + ## Methods diff --git a/docs/MockFunctionAPI.md b/docs/MockFunctionAPI.md index 526110167a84..0c7ac9e9960f 100644 --- a/docs/MockFunctionAPI.md +++ b/docs/MockFunctionAPI.md @@ -5,15 +5,9 @@ title: Mock Functions Mock functions are also known as "spies", because they let you spy on the behavior of a function that is called indirectly by some other code, rather than only testing the output. You can create a mock function with `jest.fn()`. If no implementation is given, the mock function will return `undefined` when invoked. -:::info +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`: - -```ts -import {jest} from '@jest/globals'; -``` - -::: + ## Methods diff --git a/docs/UpgradingToJest29.md b/docs/UpgradingToJest29.md index cab1555d0dc8..b4cb1f1ec506 100644 --- a/docs/UpgradingToJest29.md +++ b/docs/UpgradingToJest29.md @@ -50,15 +50,9 @@ Exports of `Mocked*` utility types from `jest-mock` package have changed. `Maybe ## TypeScript -:::info - -The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`: +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -```ts -import {jest} from '@jest/globals'; -``` - -::: + ### `jest.mocked()` diff --git a/docs/_TypeScriptExamplesNote.md b/docs/_TypeScriptExamplesNote.md new file mode 100644 index 000000000000..c1062b21976f --- /dev/null +++ b/docs/_TypeScriptExamplesNote.md @@ -0,0 +1,9 @@ +:::info + +The TypeScript examples from this page will only work as documented if you explicitly import Jest APIs: + +```ts +import {expect, jest, test} from '@jest/globals'; +``` + +::: diff --git a/website/versioned_docs/version-28.x/MockFunctionAPI.md b/website/versioned_docs/version-28.x/MockFunctionAPI.md index db8f2d5ea4b3..0b65c68ed57a 100644 --- a/website/versioned_docs/version-28.x/MockFunctionAPI.md +++ b/website/versioned_docs/version-28.x/MockFunctionAPI.md @@ -5,15 +5,9 @@ title: Mock Functions Mock functions are also known as "spies", because they let you spy on the behavior of a function that is called indirectly by some other code, rather than only testing the output. You can create a mock function with `jest.fn()`. If no implementation is given, the mock function will return `undefined` when invoked. -:::info +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`: - -```ts -import {jest} from '@jest/globals'; -``` - -::: + ## Methods diff --git a/website/versioned_docs/version-28.x/UpgradingToJest28.md b/website/versioned_docs/version-28.x/UpgradingToJest28.md index 6f858e0fd9ac..c3b70b6901a6 100644 --- a/website/versioned_docs/version-28.x/UpgradingToJest28.md +++ b/website/versioned_docs/version-28.x/UpgradingToJest28.md @@ -189,15 +189,9 @@ Known examples of packages that fails in Jest 28 are [`uuid`](https://npmjs.com/ ## TypeScript -:::info - -The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`: +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -```ts -import {jest} from '@jest/globals'; -``` - -::: + ### `jest.fn()` diff --git a/website/versioned_docs/version-28.x/_TypeScriptExamplesNote.md b/website/versioned_docs/version-28.x/_TypeScriptExamplesNote.md new file mode 100644 index 000000000000..c1062b21976f --- /dev/null +++ b/website/versioned_docs/version-28.x/_TypeScriptExamplesNote.md @@ -0,0 +1,9 @@ +:::info + +The TypeScript examples from this page will only work as documented if you explicitly import Jest APIs: + +```ts +import {expect, jest, test} from '@jest/globals'; +``` + +::: diff --git a/website/versioned_docs/version-29.0/GlobalAPI.md b/website/versioned_docs/version-29.0/GlobalAPI.md index f41f1eedcbc4..775d40d11d9c 100644 --- a/website/versioned_docs/version-29.0/GlobalAPI.md +++ b/website/versioned_docs/version-29.0/GlobalAPI.md @@ -5,6 +5,10 @@ title: Globals In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them. However, if you prefer explicit imports, you can do `import {describe, expect, test} from '@jest/globals'`. +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; + + + ## Methods import TOCInline from '@theme/TOCInline'; @@ -969,16 +973,6 @@ test.todo('add should be associative'); ## TypeScript Usage -:::info - -These TypeScript usage tips and caveats are only applicable if you import from `'@jest/globals'`: - -```ts -import {describe, test} from '@jest/globals'; -``` - -::: - ### `.each` The `.each` modifier offers few different ways to define a table of the test cases. Some of the APIs have caveats related with the type inference of the arguments which are passed to `describe` or `test` callback functions. Let's take a look at each of them. @@ -994,6 +988,8 @@ For simplicity `test.each` is picked for the examples, but the type inference is The array of objects API is most verbose, but it makes the type inference a painless task. A `table` can be inlined: ```ts +import {test} from '@jest/globals'; + test.each([ {name: 'a', path: 'path/to/a', count: 1, write: true}, {name: 'b', path: 'path/to/b', count: 3}, @@ -1005,6 +1001,8 @@ test.each([ Or declared separately as a variable: ```ts +import {test} from '@jest/globals'; + const table = [ {a: 1, b: 2, expected: 'three', extra: true}, {a: 3, b: 4, expected: 'seven', extra: false}, @@ -1021,6 +1019,8 @@ test.each(table)('table as a variable', ({a, b, expected, extra}) => { The array of arrays style will work smoothly with inlined tables: ```ts +import {test} from '@jest/globals'; + test.each([ [1, 2, 'three', true], [3, 4, 'seven', false], @@ -1033,6 +1033,8 @@ test.each([ However, if a table is declared as a separate variable, it must be typed as an array of tuples for correct type inference (this is not needed only if all elements of a row are of the same type): ```ts +import {test} from '@jest/globals'; + const table: Array<[number, number, string, boolean?]> = [ [1, 2, 'three', true], [3, 4, 'seven', false], @@ -1049,6 +1051,8 @@ test.each(table)('table as a variable example', (a, b, expected, extra) => { If all values are of the same type, the template literal API will type the arguments correctly: ```ts +import {test} from '@jest/globals'; + test.each` a | b | expected ${1} | ${2} | ${3} @@ -1062,6 +1066,8 @@ test.each` Otherwise it will require a generic type argument: ```ts +import {test} from '@jest/globals'; + test.each<{a: number; b: number; expected: string; extra?: boolean}>` a | b | expected | extra ${1} | ${2} | ${'three'} | ${true} diff --git a/website/versioned_docs/version-29.0/JestObjectAPI.md b/website/versioned_docs/version-29.0/JestObjectAPI.md index add6b8c49a6c..c679baca5cfe 100644 --- a/website/versioned_docs/version-29.0/JestObjectAPI.md +++ b/website/versioned_docs/version-29.0/JestObjectAPI.md @@ -5,6 +5,10 @@ title: The Jest Object The `jest` object is automatically in scope within every test file. The methods in the `jest` object help create mocks and let you control Jest's overall behavior. It can also be imported explicitly by via `import {jest} from '@jest/globals'`. +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; + + + ## Methods import TOCInline from '@theme/TOCInline'; diff --git a/website/versioned_docs/version-29.0/MockFunctionAPI.md b/website/versioned_docs/version-29.0/MockFunctionAPI.md index 526110167a84..0c7ac9e9960f 100644 --- a/website/versioned_docs/version-29.0/MockFunctionAPI.md +++ b/website/versioned_docs/version-29.0/MockFunctionAPI.md @@ -5,15 +5,9 @@ title: Mock Functions Mock functions are also known as "spies", because they let you spy on the behavior of a function that is called indirectly by some other code, rather than only testing the output. You can create a mock function with `jest.fn()`. If no implementation is given, the mock function will return `undefined` when invoked. -:::info +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`: - -```ts -import {jest} from '@jest/globals'; -``` - -::: + ## Methods diff --git a/website/versioned_docs/version-29.0/UpgradingToJest29.md b/website/versioned_docs/version-29.0/UpgradingToJest29.md index cab1555d0dc8..b4cb1f1ec506 100644 --- a/website/versioned_docs/version-29.0/UpgradingToJest29.md +++ b/website/versioned_docs/version-29.0/UpgradingToJest29.md @@ -50,15 +50,9 @@ Exports of `Mocked*` utility types from `jest-mock` package have changed. `Maybe ## TypeScript -:::info - -The TypeScript examples from this page will only work as documented if you import `jest` from `'@jest/globals'`: +import TypeScriptExamplesNote from './_TypeScriptExamplesNote.md'; -```ts -import {jest} from '@jest/globals'; -``` - -::: + ### `jest.mocked()` diff --git a/website/versioned_docs/version-29.0/_TypeScriptExamplesNote.md b/website/versioned_docs/version-29.0/_TypeScriptExamplesNote.md new file mode 100644 index 000000000000..c1062b21976f --- /dev/null +++ b/website/versioned_docs/version-29.0/_TypeScriptExamplesNote.md @@ -0,0 +1,9 @@ +:::info + +The TypeScript examples from this page will only work as documented if you explicitly import Jest APIs: + +```ts +import {expect, jest, test} from '@jest/globals'; +``` + +:::