diff --git a/CHANGELOG.md b/CHANGELOG.md index 754f602dd2bb..9bb053236ea6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ ### Chore & Maintenance +- `[docs]` Add docs for using mocks in TypeScript([#10415](https://github.com/facebook/jest/pull/10415)) - `[jest-cli]` chore: standardize files and folder names ([#10698](https://github.com/facebook/jest/pull/1098)) ### Performance diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md index 64a06250e80d..fa317619a57b 100644 --- a/docs/GettingStarted.md +++ b/docs/GettingStarted.md @@ -171,3 +171,11 @@ module.exports = { ``` However, there are some [caveats](https://babeljs.io/docs/en/babel-plugin-transform-typescript#caveats) to using TypeScript with Babel. Because TypeScript support in Babel is purely transpilation, Jest will not type-check your tests as they are run. If you want that, you can use [ts-jest](https://github.com/kulshekhar/ts-jest) instead, or just run the TypeScript compiler [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html) separately (or as part of your build process). + +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. + +> 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. + +```bash +yarn add --dev @types/jest +``` diff --git a/docs/MockFunctionAPI.md b/docs/MockFunctionAPI.md index 563e614b8adf..5bb9002d4069 100644 --- a/docs/MockFunctionAPI.md +++ b/docs/MockFunctionAPI.md @@ -316,3 +316,133 @@ test('async test', async () => { await asyncMock(); // throws "Async error" }); ``` + +## TypeScript + +Jest itself is written in [TypeScript](https://www.typescriptlang.org). + +If you are using [Create React App](https://create-react-app.dev) then the [TypeScript template](https://create-react-app.dev/docs/adding-typescript/) has everything you need to start writing tests in TypeScript. + +Otherwise, please see our [Getting Started](GettingStarted.md#using-typescript) guide for to get setup with TypeScript. + +You can see an example of using Jest with TypeScript in our [GitHub repository](https://github.com/facebook/jest/tree/master/examples/typescript). + +### `jest.MockedFunction` + +> `jest.MockedFunction` is available in the `@types/jest` module from version `24.9.0`. + +The following examples will assume you have an understanding of how [Jest mock functions work with JavaScript](MockFunctions.md). + +You can use `jest.MockedFunction` to represent a function that has been replaced by a Jest mock. + +Example using [automatic `jest.mock`](JestObjectAPI.md#jestmockmodulename-factory-options): + +```ts +// Assume `add` is imported and used within `calculate`. +import add from './add'; +import calculate from './calc'; + +jest.mock('./add'); + +// Our mock of `add` is now fully typed +const mockAdd = add as jest.MockedFunction; + +test('calculate calls add', () => { + calculate('Add', 1, 2); + + expect(mockAdd).toBeCalledTimes(1); + expect(mockAdd).toBeCalledWith(1, 2); +}); +``` + +Example using [`jest.fn`](JestObjectAPI.md#jestfnimplementation): + +```ts +// Here `add` is imported for its type +import add from './add'; +import calculate from './calc'; + +test('calculate calls add', () => { + // Create a new mock that can be used in place of `add`. + const mockAdd = jest.fn() as jest.MockedFunction; + + // Note: You can use the `jest.fn` type directly like this if you want: + // const mockAdd = jest.fn, Parameters>(); + // `jest.MockedFunction` is a more friendly shortcut. + + // Now we can easily set up mock implementations. + // All the `.mock*` API can now give you proper types for `add`. + // https://jestjs.io/docs/en/mock-function-api + + // `.mockImplementation` can now infer that `a` and `b` are `number` + // and that the returned value is a `number`. + mockAdd.mockImplementation((a, b) => { + // Yes, this mock is still adding two numbers but imagine this + // was a complex function we are mocking. + return a + b + })); + + // `mockAdd` is properly typed and therefore accepted by + // anything requiring `add`. + calculate(mockAdd, 1 , 2); + + expect(mockAdd).toBeCalledTimes(1); + expect(mockAdd).toBeCalledWith(1, 2); +}) +``` + +### `jest.MockedClass` + +> `jest.MockedClass` is available in the `@types/jest` module from version `24.9.0`. + +The following examples will assume you have an understanding of how [Jest mock classes work with JavaScript](Es6ClassMocks.md). + +You can use `jest.MockedClass` to represent a class that has been replaced by a Jest mock. + +Converting the [ES6 Class automatic mock example](Es6ClassMocks.md#automatic-mock) would look like this: + +```ts +import SoundPlayer from '../sound-player'; +import SoundPlayerConsumer from '../sound-player-consumer'; + +jest.mock('../sound-player'); // SoundPlayer is now a mock constructor + +const SoundPlayerMock = SoundPlayer as jest.MockedClass; + +beforeEach(() => { + // Clear all instances and calls to constructor and all methods: + SoundPlayerMock.mockClear(); +}); + +it('We can check if the consumer called the class constructor', () => { + const soundPlayerConsumer = new SoundPlayerConsumer(); + expect(SoundPlayerMock).toHaveBeenCalledTimes(1); +}); + +it('We can check if the consumer called a method on the class instance', () => { + // Show that mockClear() is working: + expect(SoundPlayerMock).not.toHaveBeenCalled(); + + const soundPlayerConsumer = new SoundPlayerConsumer(); + // Constructor should have been called again: + expect(SoundPlayerMock).toHaveBeenCalledTimes(1); + + const coolSoundFileName = 'song.mp3'; + soundPlayerConsumer.playSomethingCool(); + + // mock.instances is available with automatic mocks: + const mockSoundPlayerInstance = SoundPlayerMock.mock.instances[0]; + + // However, it will not allow access to `.mock` in TypeScript as it + // is returning `SoundPlayer`. Instead, you can check the calls to a + // method like this fully typed: + expect(SoundPlayerMock.prototype.playSoundFile.mock.calls[0][0]).toEqual( + coolSoundFileName, + ); + // Equivalent to above check: + expect(SoundPlayerMock.prototype.playSoundFile).toHaveBeenCalledWith( + coolSoundFileName, + ); + expect(SoundPlayerMock.prototype.playSoundFile).toHaveBeenCalledTimes(1); +}); +``` diff --git a/website/versioned_docs/version-22.x/GettingStarted.md b/website/versioned_docs/version-22.x/GettingStarted.md index ecdff367feb8..6600ee04ce3b 100644 --- a/website/versioned_docs/version-22.x/GettingStarted.md +++ b/website/versioned_docs/version-22.x/GettingStarted.md @@ -139,3 +139,11 @@ Jest can be used in projects that use [parcel-bundler](https://parceljs.org/) to ### Using TypeScript To use TypeScript in your tests you can use [ts-jest](https://github.com/kulshekhar/ts-jest). + +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. + +> 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. + +```bash +yarn add --dev @types/jest +``` diff --git a/website/versioned_docs/version-23.x/GettingStarted.md b/website/versioned_docs/version-23.x/GettingStarted.md index 08560199e960..b2c69ee168b8 100644 --- a/website/versioned_docs/version-23.x/GettingStarted.md +++ b/website/versioned_docs/version-23.x/GettingStarted.md @@ -147,3 +147,11 @@ Jest can be used in projects that use [parcel-bundler](https://parceljs.org/) to ### Using TypeScript To use TypeScript in your tests you can use [ts-jest](https://github.com/kulshekhar/ts-jest). + +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. + +> 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. + +```bash +yarn add --dev @types/jest +``` diff --git a/website/versioned_docs/version-24.x/GettingStarted.md b/website/versioned_docs/version-24.x/GettingStarted.md index b2c6586b9e53..cce40437d0a8 100644 --- a/website/versioned_docs/version-24.x/GettingStarted.md +++ b/website/versioned_docs/version-24.x/GettingStarted.md @@ -172,3 +172,11 @@ module.exports = { ``` However, there are some [caveats](https://babeljs.io/docs/en/babel-plugin-transform-typescript#caveats) to using TypeScript with Babel. Because TypeScript support in Babel is purely transpilation, Jest will not type-check your tests as they are run. If you want that, you can use [ts-jest](https://github.com/kulshekhar/ts-jest) instead, or just run the TypeScript compiler [tsc](https://www.typescriptlang.org/docs/handbook/compiler-options.html) separately (or as part of your build process). + +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. + +> 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. + +```bash +yarn add --dev @types/jest +``` diff --git a/website/versioned_docs/version-24.x/MockFunctionAPI.md b/website/versioned_docs/version-24.x/MockFunctionAPI.md index 7b1339094340..7af3cae090f3 100644 --- a/website/versioned_docs/version-24.x/MockFunctionAPI.md +++ b/website/versioned_docs/version-24.x/MockFunctionAPI.md @@ -317,3 +317,133 @@ test('async test', async () => { await asyncMock(); // throws "Async error" }); ``` + +## TypeScript + +Jest itself is written in [TypeScript](https://www.typescriptlang.org). + +If you are using [Create React App](https://create-react-app.dev) then the [TypeScript template](https://create-react-app.dev/docs/adding-typescript/) has everything you need to start writing tests in TypeScript. + +Otherwise, please see our [Getting Started](GettingStarted.md#using-typescript) guide for to get setup with TypeScript. + +You can see an example of using Jest with TypeScript in our [GitHub repository](https://github.com/facebook/jest/tree/master/examples/typescript). + +### `jest.MockedFunction` + +> `jest.MockedFunction` is available in the `@types/jest` module from version `24.9.0`. + +The following examples will assume you have an understanding of how [Jest mock functions work with JavaScript](MockFunctions.md). + +You can use `jest.MockedFunction` to represent a function that has been replaced by a Jest mock. + +Example using [automatic `jest.mock`](JestObjectAPI.md#jestmockmodulename-factory-options): + +```ts +// Assume `add` is imported and used within `calculate`. +import add from './add'; +import calculate from './calc'; + +jest.mock('./add'); + +// Our mock of `add` is now fully typed +const mockAdd = add as jest.MockedFunction; + +test('calculate calls add', () => { + calculate('Add', 1, 2); + + expect(mockAdd).toBeCalledTimes(1); + expect(mockAdd).toBeCalledWith(1, 2); +}); +``` + +Example using [`jest.fn`](JestObjectAPI.md#jestfnimplementation): + +```ts +// Here `add` is imported for its type +import add from './add'; +import calculate from './calc'; + +test('calculate calls add', () => { + // Create a new mock that can be used in place of `add`. + const mockAdd = jest.fn() as jest.MockedFunction; + + // Note: You can use the `jest.fn` type directly like this if you want: + // const mockAdd = jest.fn, Parameters>(); + // `jest.MockedFunction` is a more friendly shortcut. + + // Now we can easily set up mock implementations. + // All the `.mock*` API can now give you proper types for `add`. + // https://jestjs.io/docs/en/mock-function-api + + // `.mockImplementation` can now infer that `a` and `b` are `number` + // and that the returned value is a `number`. + mockAdd.mockImplementation((a, b) => { + // Yes, this mock is still adding two numbers but imagine this + // was a complex function we are mocking. + return a + b + })); + + // `mockAdd` is properly typed and therefore accepted by + // anything requiring `add`. + calculate(mockAdd, 1 , 2); + + expect(mockAdd).toBeCalledTimes(1); + expect(mockAdd).toBeCalledWith(1, 2); +}) +``` + +### `jest.MockedClass` + +> `jest.MockedClass` is available in the `@types/jest` module from version `24.9.0`. + +The following examples will assume you have an understanding of how [Jest mock classes work with JavaScript](Es6ClassMocks.md). + +You can use `jest.MockedClass` to represent a class that has been replaced by a Jest mock. + +Converting the [ES6 Class automatic mock example](Es6ClassMocks.md#automatic-mock) would look like this: + +```ts +import SoundPlayer from '../sound-player'; +import SoundPlayerConsumer from '../sound-player-consumer'; + +jest.mock('../sound-player'); // SoundPlayer is now a mock constructor + +const SoundPlayerMock = SoundPlayer as jest.MockedClass; + +beforeEach(() => { + // Clear all instances and calls to constructor and all methods: + SoundPlayerMock.mockClear(); +}); + +it('We can check if the consumer called the class constructor', () => { + const soundPlayerConsumer = new SoundPlayerConsumer(); + expect(SoundPlayerMock).toHaveBeenCalledTimes(1); +}); + +it('We can check if the consumer called a method on the class instance', () => { + // Show that mockClear() is working: + expect(SoundPlayerMock).not.toHaveBeenCalled(); + + const soundPlayerConsumer = new SoundPlayerConsumer(); + // Constructor should have been called again: + expect(SoundPlayerMock).toHaveBeenCalledTimes(1); + + const coolSoundFileName = 'song.mp3'; + soundPlayerConsumer.playSomethingCool(); + + // mock.instances is available with automatic mocks: + const mockSoundPlayerInstance = SoundPlayerMock.mock.instances[0]; + + // However, it will not allow access to `.mock` in TypeScript as it + // is returning `SoundPlayer`. Instead, you can check the calls to a + // method like this fully typed: + expect(SoundPlayerMock.prototype.playSoundFile.mock.calls[0][0]).toEqual( + coolSoundFileName, + ); + // Equivalent to above check: + expect(SoundPlayerMock.prototype.playSoundFile).toHaveBeenCalledWith( + coolSoundFileName, + ); + expect(SoundPlayerMock.prototype.playSoundFile).toHaveBeenCalledTimes(1); +}); +```