feat(@jest/globals): add jest.Mocked, jest.MockedClass, jest.MockedFunction and jest.MockedObject utility types

[mrazauskas]

From #12424 (comment)

Summary

This PR adds utility types jest.Mocked, jest.MockedClass, jest.MockedFunction and jest.MockedObject to the Jest object.

Test plan

Type tests are added.

[SimenB]

exciting!

[SimenB]

@mrazauskas hiya! what's the state here? 🙂 Would love to land it for 29!

[SimenB]

This is shaping up! Do you think we should move changes in jest-mock to a separate PR, so this one is just exposing jest.Mocked etc?

[mrazauskas]

It is a good question: if there is a need to expose jest.Mocked* helper types at all?

The only reason I see is that having jest.Mocked* makes it easier to migrate from @types/jest, but do we need them? The jest.Mocked<T> from this PR can be used instead of jest.MockedClass<T> and jest.MockedFunction<T>. It simply returns jest.MockedClass<T> or jest.MockedFunction<T> if class or function type is passed.

jest.Mocked<T> does the whole job. Other two will just take space in documentation (and will take time to write it too).

More over jest.mocked() does all what jest.Mocked<T> can do (see 715c564). Also migration to jest.mocked() is simple enough as we can see in #13117.

Perhaps all we need is jest.mocked()?

---

My only problem with jest.mocked() – shallow mocking by default. For instance, MockedClass must be deep. Otherwise MockSomeClass.prototype.methodA.mock.calls[0] does not work, because methodA is nested inside an object.

Also looking at jest.mocked(someFn, true) it is not clear what true does without reading docs. (By the way, jest.mocked(SomeClass) and jest.mocked(SomeClass, true) should be equivalent.)

---

What if we would skip adding jest.Mocked* helpers in favour of jest.mocked() and would swap the default of jest.mock() to deep mocking? Shallow mocking could be set though jest.mocked(someFn, {shallow: true})? Simple and readable? Or too much breaking?

[SimenB]

It's useful if you use it as argument I think.

function helper(thing: jest.Mocked<SomeType>) {
  // ...
}

Right?

As for deep vs not deep - sounds like a separate PR from this?

[mrazauskas]

Right. jest.Mocked<T> is useful. I just came up with one more use case. Let’s keep add it.

For me it makes sense to keep jest.Mocked<T>s implementation deep mocked. It was not before, in this PR implementation is deep. Does not sounds like jest.MockedDeep<T> should be introduced. If it is fine to keep it deep, then swapping defaults of jest.mocked() makes even more sense.

Alright. Let’s split this PR (;

[mrazauskas]

@SimenB All done. Finally ;D

[SimenB]

🎉

[SimenB]

I love that we're finally adding type-only jest.* exports now! 👍

Hopefully we'll be able to replace most of @types/jest soonish with this approach

[SimenB]

Woo!

[SimenB]

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

[SimenB]

https://github.com/facebook/jest/releases/tag/v29.0.0

[github-actions]

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.