fix(expect): expose AsymmetricMatchers and RawMatcherFn interfaces

[mrazauskas]

Summary

Just wanted to check if now it is possible to extend interfaces of matchers for expect.extend(). Couple of details missing:

• AsymmetricMatchers interface is not yet public, but it should be. And then this is possible:

declare module 'expect' {
  interface AsymmetricMatchers {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
  interface Matchers<R> {
    toBeWithinRange(floor: number, ceiling: number): void;
  }
}

• exposed RawMatcherFn is useful internally and provides type safety for this pattern:

import {expect} from '@jest/globals';
import type {RawMatcherFn} from 'expect';

const someCustomMatcher: RawMatcherFn = (x, y, z) => {
  return {
    message: () => '',
    pass: true,
  };
};

expect.extend({
  someCustomMatcher,
});

Nice! Shall I add it to docs as well?

An example is added to examples folder. Regarding the docs update, I think it would be better idea to move expect.extend() to a separate guide chapter similar to "Code Transformation". The expect.extend() section is already too long inside Expect chapter. So perhaps I will make another PR with this change.

Test plan

Type tests are added.

[SimenB]

Nice! Shall I add it to docs as well?

Yes please! 😀

[SimenB]

yay!

[SimenB]

do we need workspace:* here so we resolve to the versions we want?

[SimenB]

potentially just resolutions in root: https://github.com/facebook/jest/blob/60eb4160b5258eed5faf381e0c8ea6662076cc6c/package.json#L157-L159

[SimenB]

we should export this type probably

[mrazauskas]

Hm.. But this is just a helper for testing. Perhaps that’s fine?

[SimenB]

it's a copy of https://github.com/facebook/jest/blob/60eb4160b5258eed5faf381e0c8ea6662076cc6c/packages/expect/src/types.ts#L46-L49, no?

[mrazauskas]

Got it. I though you speak about exporting typeof jestMatcherUtil somehow.

[mrazauskas]

Do you think MatcherUtils type should be public? Type test is importing from build, not from source.

[SimenB]

it was just some duplication that felt unnecessary, I don't feel strongly here 🙂

[SimenB]

there's no way we can avoid the duplication here, right?

[mrazauskas]

Wrestled with this. No luck. Alternative idea: what if expect.extend() would return Expect extended with types of custom matchers? Right now expect.extend() returns void. The proposed return value would be only useful for typings. No need to extend, augment, etc.

import {expect as jestExpect} from '@jest/globals';
import customMatcher from 'customMatcher';

const expect = jestExpect.extend({
  customMatcher,
});

// here `expect.customMatcher()` is fully typed

[mrazauskas]

Drafty, but working prototype (in this case, toBeWithinRange takes two arguments and both are inferred):

[SimenB]

I like it! 😃 We need "old" way to continue working of course, but doing it this way seems smoother

[SimenB]

awesome!!

[SimenB]

Do we need Raw in the name? Doesn't seem like something one should use when exported 😅

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