feat(expect): replace RawMatcherFn with MatcherFunction and MatcherFunctionWithState types

[mrazauskas]

Summary

It may be not the best idea to expose RawMatcherFn from expect. That was my initiative (see #12363), so fixing it. Easier to explain with example:

https://github.com/facebook/jest/blob/faef0b4b7082df574a0e4423b86d468847360f17/packages/expect/src/types.ts#L23-L24

const toBeWithinRange: RawMatcherFn = (actual: number, floor: number, ceiling: number) => {
  // implementation
};

In the example above RawMatcherFn will simply turn all three number types into any. Ups.. Found it while working on #12363 (comment). Everything what I can infer with expect.extend({toBeWithinRange}) is floor: any, ceiling: any.

It felt like RawMatcherFn should give some type safety here. For example, the number of arguments? Let’s check. Hardly possible to imagine any implementation without actual (or received). The rest of arguments are optional (for instance .toBeNull()). No use of actual: any, expected?: any, options?: any and it is not good idea to any types of all args.

What about return type? All we need is ExpectationResult, right? Like this:

const toBeWithinRange = (actual: number, floor: number, ceiling: number): ExpectationResult => {
  // implementation
};

This way one can ensure that { pass: boolean; message(): string; } will be returned as required. That’s good. Also arguments are not any. That’s also good. And it seems that ExpectationResult is all we need internally too. Or?

---

Edit: One more detail. RawMatcherFn also has this type. That’s important, of course. Just checked, it all works:

function toHaveContext(this: MatcherState, received: string): ExpectationResult {
  // implementation
};

Test plan

Green CI.

[mrazauskas]

This function has inferred return type of ExpectationResult without this extra type.

[mrazauskas]

Puzzle. To be precise this type should be () => (...args: Array<unknown>) => ExpectationResult, but my version eliminates these @ts-expect-error: https://github.com/facebook/jest/blob/faef0b4b7082df574a0e4423b86d468847360f17/packages/jest-jasmine2/src/jestExpect.ts#L50-L60

[codecov-commenter]

Codecov Report

Merging #12376 (b16b3a4) into main (faef0b4) will increase coverage by 0.00%.
The diff coverage is 73.68%.

@@           Coverage Diff           @@
##             main   #12376   +/-   ##
=======================================
  Coverage   68.47%   68.47%           
=======================================
  Files         324      324           
  Lines       16967    16968    +1     
  Branches     5060     5060           
=======================================
+ Hits        11618    11619    +1     
  Misses       5317     5317           
  Partials       32       32           

Impacted Files	Coverage Δ
packages/expect/src/index.ts	91.27% <ø> (ø)
packages/jest-jasmine2/src/jestExpect.ts	0.00% <0.00%> (ø)
packages/jest-snapshot/src/index.ts	78.75% <87.50%> (+0.13%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update faef0b4...b16b3a4. Read the comment docs.

[SimenB]

@mrazauskas can we land this now, you think? Just so the types are closer to what we want than #12363. I wanna make a new alpha release without that in it 🙂 We can still revisit of course, but not publishing stuff we know will be yanked makes sense

[mrazauskas]

@SimenB Sure. Just let me take one last look.

The thing is that I got stuck trying to use the new MatcherFunction internally. Some changes are needed and I was preparing few PRs to make that possible. But we can land this now with todo comment and iterate to fix it all.

By the way, should ExpectationResult be exposed or not? Hm.. I am 50/50 about it. What you think?

[SimenB]

The thing is that I got stuck trying to use the new MatcherFunction internally. Some changes are needed and I was preparing few PRs to make that possible. But we can land this now with todo comment and iterate to fix it all.

Exciting stuff! II really hope these awesome changes you're working on will let us use @jest/globals directly in @types/jest, that way custom matchers can all depend on @jest/globals instead.

By the way, should ExpectationResult be exposed or not? Hm.. I am 50/50 about it. What you think?

Hmm, let's keep it out for now, and if there's a use case we can expose it? Always easier to add than remove stuff 😀

---

Semi-related - thoughts about a @jest/expect which adds the snapshot matchers? That way people can use expect as a "generic" assertion module, @jest/expect if it's only for Jest. Instead of @jest/globals which also pulls in describe test etc.. Feels slightly more natural for libraries only doing custom assertions (like jest-extended).

@jest/expect would then do the interface merging for the snapshot matchers and the extend call itself.

Not sure, might not make sense 😀

[SimenB]

this is great, I'm super excited about where this is going!

[mrazauskas]

Same here. Thanks for good questions. It is interesting exercise to think about and to shape these types.

---

Semi-related - thoughts about a @jest/expect which adds the snapshot matchers? That way people can use expect as a "generic" assertion module, @jest/expect if it's only for Jest.

Sounds interesting. And then @jest/globals could pull types from @jest/expect too?

[mrazauskas]

Wait.. So, you think @jest/expect would be simply this one + right types: https://github.com/facebook/jest/blob/main/packages/jest-circus/src/legacy-code-todo-rewrite/jestExpect.ts. That might be very good.

[SimenB]

Semi-related - thoughts about a @jest/expect which adds the snapshot matchers? That way people can use expect as a "generic" assertion module, @jest/expect if it's only for Jest.

Sounds interesting. And then @jest/globals could pull types from @jest/expect too?

Yep

Wait.. So, you think @jest/expect would be simply this one + right types: https://github.com/facebook/jest/blob/main/packages/jest-circus/src/legacy-code-todo-rewrite/jestExpect.ts. That might be very good.

Yeah, exactly

[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.