refactor(jest-mock)!: simplify usage of `jest.fn` generic type arguments by mrazauskas · Pull Request #12489 · jestjs/jest

mrazauskas · 2022-02-24T17:27:31Z

Summary

jest.fn and jest.spyOn depend on Mock and MockInstance types. These take two generic type arguments: the returned value, parameters type. That works just fine internally, but makes usage hard for on the user side. For instance, here is a line from Jest docs:

const mockAdd = jest.fn() as jest.MockedFunction<typeof add>;

All looks fine at first glance, but the thing is that type returned by jest.fn is Mock and it is slightly different from MockedFunction. As it was pointed out in the link issue, to have the right type currently user should do something like this:

const mockAdd = jest.fn<ReturnType<typeof add>, Parameters<typeof add>>();

This PR makes it possible to type jest.fn in much more simple way (which is also more precise than type casting using MockedFunction):

const mockAdd = jest.fn<typeof add>();

Looks like I made it work as expected. Have to take a second look tomorrow at a couple of anys here and there. Seems like internally they are necessary. On user side, everything should default to unknown.

Test plan

It was priceless to have type tests in place! All should pass.

mrazauskas · 2022-02-25T12:43:20Z

Trying out types while looking through examples in docs. It might be good idea to add a tab with TypeScript flavoured examples. Just trying out what is possible and how it works.

With current types:

const asyncMock = fn<Promise<string>, []>()
  .mockResolvedValue('default')
  .mockResolvedValueOnce('first call')
  .mockResolvedValueOnce('second call');

const mock = fn<number, []>()
  .mockReturnValue(42)
  .mockReturnValueOnce(35)
  .mockReturnValueOnce(12);

With types of this branch (more verbose, but also more clear):

const asyncMock = fn<() => Promise<string>>()
  .mockResolvedValue('default')
  .mockResolvedValueOnce('first call')
  .mockResolvedValueOnce('second call');

const mock = fn<() => number>()
  .mockReturnValue(42)
  .mockReturnValueOnce(35)
  .mockReturnValueOnce(12);

Of course, this is only necessary if fn() lacks implementation, otherwise everything is typed (also mockResolvedValue throws TS error with sync implementation):

const asyncMock = fn(async () => 'default')
  .mockResolvedValueOnce('first call')
  .mockResolvedValueOnce('second call');

const mock = fn(() => 42)
  .mockReturnValueOnce(35)
  .mockReturnValueOnce(12);

mrazauskas · 2022-02-25T20:37:33Z

Just push docs with TS examples. Preview is here – https://deploy-preview-12489--jestjs.netlify.app/docs/next/mock-function-api

(Might be there is better way to setup tabs. I have zero experience with Docusaurus, so just followed their docs.)

docs/MockFunctionAPI.md

mrazauskas · 2022-02-26T09:35:27Z

docs/MockFunctionAPI.md

+```bash
 expect(mockedFunction).toHaveBeenCalled()
-
-Expected mock function "mockedFunction" to have been called, but it was not called.


The actual message is (feels to be redundant, or?):

Expected number of calls: >= 1 Received number of calls: 0

really? that's a regression then. The point is that we print the mockName provided

The name gets printed. The line expect(mockedFunction).toHaveBeenCalled() is correct, but Expected mock function "mockedFunction" to have been called, but it was not called prints as Expected number of calls... I will double check.

Aha. Still a regression, we shouldn't be printing numbers when we're expecting any. Makes sense when we expect none, tho

Alright. Would be better to leave the line in place and to open an issue? So we don’t forget to look at it. Right?

docs/MockFunctionAPI.md

packages/jest-runtime/src/index.ts

SimenB · 2022-02-26T09:46:21Z

Loving the docs changes! 👍 Good idea to use tabs

mrazauskas · 2022-02-26T09:48:43Z

packages/jest-mock/src/index.ts

-export interface Mock<T, Y extends Array<unknown> = Array<unknown>>
+type UnknownFunction = (...args: Array<unknown>) => unknown;
+
+export interface Mock<T extends FunctionLike = UnknownFunction>


There is a need to keep anys in type FunctionLike = (...args: any) => any. It does not work with unknowns either internally, or something breaks in tests. Despite anys, this is not any (; It is AnyFunction and that’s a constrain. Passing anything what is not a function will throw TS error. To avoid anys leak to user side I used defaults of (...args: Array<unknown>) => unknown. This means that using fn() without any implementation will default to unknown, if implementation is provided types are inferred.

Trying to explain this in more detail, because I repeated this pattern several times. Internally all what’s necessary is to be sure that we have a function, hence simply any function works. It also works as a constrain. But the default on user side always is (...args: Array<unknown>) => unknown.

Sounds good 👍 probably worth a code comment?

mrazauskas · 2022-02-26T10:01:55Z

Loving the docs changes! 👍 Good idea to use tabs

The credits goes to Playwright – https://playwright.dev/docs/intro#first-test

They are doing it in much cleaner way. I couldn’t figure out if they use some plugin or is this some React component? https://github.com/microsoft/playwright/blob/80a38a39c2c66cfb082ad1031dbddd537553380e/docs/src/intro-js.md?plain=1#L52

SimenB

yay!

changelog? 😀

docs/MockFunctionAPI.md

packages/jest-mock/__typetests__/mock-functions.test.ts

docs/MockFunctionAPI.md

SimenB · 2022-02-26T11:21:15Z

docs/MockFunctionAPI.md

+});
+```
+
 ### `jest.MockedFunction`


should we remove this as well? comes from @types/jest and not us

Right. I took it out and will bring it back after jest.Mocked refactor. What about that note on Create React App? Just above?

yeah, kill it. only thing under the TypeScript heading should be either pointing to "getting started" or examples using jest from @jest/globals. All the other stuff (CRA, "see this repo", "jest is written in TS") should go, IMO

mrazauskas · 2022-02-26T12:26:49Z

docs/MockFunctionAPI.md

-  expect(mockAdd).toBeCalledWith(1, 2);
-});
-```
+### `jest.fn(implementation?)`


By the way, I double checked if the example works. All is correct. Will add it to examples folder later. TypeScript example will need more changes.

convert back to draft so I don't accidentally merge? 😀

packages/jest-mock/src/index.ts

Co-authored-by: Simen Bekkhus <sbekkhus91@gmail.com>

SimenB

this is fantastic stuff @mrazauskas! Thank you so much for diving in and fixing this 👍

SimenB · 2022-02-26T15:50:49Z

docs/MockFunctionAPI.md

-_Note: `jest.fn(implementation)` is a shorthand for `jest.fn().mockImplementation(implementation)`._
-
-For example:
+Both `jest.fn(fn)` and `jest.fn().mockImplementation(fn)` are equivalent. For instance, you can use `.mockImplementation()` to replace the implementation of a mock:


stick in :::tip? or note I guess

The idea was to refactor this note into a sentence, which should sell .mockImplementation(). If both are equivalent, why choose the longer one? For instance, .mockResolveValue() or .mockRejectedValue() have similar sentence followed by example. That’s why I tweak the following example too. Does not work? Hm.. Read it all again. I deleted too much. Will fix it.

I think the example change is good since it's shorter, but I think highlighting the fact the two approaches are the same is a good idea 🙂

Right. I reverted most of text. It sounds good.

mrazauskas · 2022-02-26T18:15:06Z

Thank you so much for diving in and fixing this 👍

It was fun to dive in. Also I am happy with the result. Internals are cleaner, usage is simplified and we have a few more type tests too ;D

bfaulk96 · 2022-02-28T21:06:22Z

When should we expect this in a release?

SimenB · 2022-02-28T21:51:22Z

I can make one tomorrow (bedtime here now)

bfaulk96 · 2022-02-28T21:52:26Z

Perfect! Haha sorry, not trying to rush you by any means, was just curious 😄

SimenB · 2022-03-01T08:40:03Z

https://github.com/facebook/jest/releases/tag/v28.0.0-alpha.6

github-actions · 2022-04-01T00:08:15Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

refactor(jest-mock): Mock generic type arguments

1132c7b

facebook-github-bot added the cla signed label Feb 24, 2022

mrazauskas added 2 commits February 25, 2022 22:30

TS examples

7df0d63

fix ts

a08489e

mrazauskas added 5 commits February 26, 2022 09:19

improve docs

561b907

refactor types

4dce116

tiny fix

3f7fa09

reduce diff

bba8fdf

reduce diff

ab690af

SimenB reviewed Feb 26, 2022

View reviewed changes

docs/MockFunctionAPI.md Show resolved Hide resolved

mrazauskas commented Feb 26, 2022

View reviewed changes

docs/MockFunctionAPI.md Show resolved Hide resolved

mrazauskas commented Feb 26, 2022

View reviewed changes

packages/jest-runtime/src/index.ts Show resolved Hide resolved

mrazauskas commented Feb 26, 2022

View reviewed changes

mrazauskas marked this pull request as ready for review February 26, 2022 09:48

SimenB approved these changes Feb 26, 2022

View reviewed changes

docs/MockFunctionAPI.md Show resolved Hide resolved

packages/jest-mock/__typetests__/mock-functions.test.ts Show resolved Hide resolved

tweak docs

2b1f2ab

SimenB reviewed Feb 26, 2022

View reviewed changes

docs/MockFunctionAPI.md Show resolved Hide resolved

SimenB reviewed Feb 26, 2022

View reviewed changes

mrazauskas added 2 commits February 26, 2022 13:35

add comment

b649fd2

more docs

c24d45d

mrazauskas commented Feb 26, 2022

View reviewed changes

mrazauskas marked this pull request as draft February 26, 2022 12:30

mrazauskas added 3 commits February 26, 2022 14:43

tip

b65d40a

add changelog entry

d325678

cleaner getMetadata

d2e72f2

mrazauskas added 4 commits February 26, 2022 15:06

bring back few generics

10f5596

two more bits

7e9c4a2

really last ones

7c61681

this is it

feb5722

SimenB reviewed Feb 26, 2022

View reviewed changes

packages/jest-mock/src/index.ts Show resolved Hide resolved

SimenB reviewed Feb 26, 2022

View reviewed changes

packages/jest-mock/src/index.ts Outdated Show resolved Hide resolved

mrazauskas and others added 5 commits February 26, 2022 15:35

Update packages/jest-mock/src/index.ts

6b0a31d

Co-authored-by: Simen Bekkhus <sbekkhus91@gmail.com>

fix getMetadata types

2cfbb5f

better

f7312dd

remove unnescesary FunctionLike

f5c620d

Merge branch 'main'

4ec19fe

mrazauskas marked this pull request as ready for review February 26, 2022 15:22

mrazauskas requested a review from SimenB February 26, 2022 15:23

SimenB approved these changes Feb 26, 2022

View reviewed changes

last bit of docs

4171124

SimenB merged commit b0dc2e4 into jestjs:main Feb 26, 2022

mrazauskas deleted the refactor-Mock-generic-type-arguments branch February 26, 2022 18:40

SimenB mentioned this pull request Feb 27, 2022

Introduce a more flexible and better typed way to mock APIs #7832

Open

mrazauskas mentioned this pull request Mar 11, 2022

refactor(@jest/fake-timers): improve internal typings of legacy fake timers #12567

Merged

github-actions bot locked as resolved and limited conversation to collaborators Apr 1, 2022

Uh oh!

Conversation

mrazauskas commented Feb 24, 2022

Summary

Test plan

Uh oh!

mrazauskas commented Feb 25, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrazauskas commented Feb 25, 2022

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

SimenB commented Feb 26, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrazauskas commented Feb 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SimenB left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

SimenB left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SimenB Feb 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrazauskas commented Feb 26, 2022

Uh oh!

bfaulk96 commented Feb 28, 2022

Uh oh!

SimenB commented Feb 28, 2022

Uh oh!

bfaulk96 commented Feb 28, 2022

Uh oh!

SimenB commented Mar 1, 2022

Uh oh!

github-actions bot commented Apr 1, 2022

Uh oh!

mrazauskas commented Feb 25, 2022 •

edited

Loading

mrazauskas commented Feb 26, 2022 •

edited

Loading

SimenB Feb 26, 2022 •

edited

Loading