Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(expect, @jest/expect): infer type of *ReturnedWith matchers argument #13278

Merged
merged 9 commits into from
Sep 20, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/expect/__typetests__/expect.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ import {
} from 'expect';
import type * as jestMatcherUtils from 'jest-matcher-utils';

type M = Matchers<void>;
type M = Matchers<void, unknown>;
type N = Matchers<void>;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is this N for? 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just three test – takes two type args, but allows passing juts one and (below) errors if type args are missing.

Some time ago I added second arg without default. That was a breaking change and a user raised an issue. This test was added back in these days, but became unnecessary then @jest/expect package was introduced. Now it is needed again.

One day this will be wrapped with nice test("required type arguments", () => { /.... Good enough for now (;


expectError(() => {
type E = Matchers;
Expand Down
38 changes: 25 additions & 13 deletions packages/expect/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -94,9 +94,9 @@ export interface BaseExpect {
}

export type Expect = {
<T = unknown>(actual: T): Matchers<void> &
Inverse<Matchers<void>> &
PromiseMatchers;
<T = unknown>(actual: T): Matchers<void, T> &
Inverse<Matchers<void, T>> &
PromiseMatchers<T>;
} & BaseExpect &
AsymmetricMatchers &
Inverse<Omit<AsymmetricMatchers, 'any' | 'anything'>>;
Expand All @@ -118,36 +118,41 @@ export interface AsymmetricMatchers {
stringMatching(sample: string | RegExp): AsymmetricMatcher;
}

type PromiseMatchers = {
type PromiseMatchers<T = unknown> = {
/**
* Unwraps the reason of a rejected promise so any other matcher can be chained.
* If the promise is fulfilled the assertion fails.
*/
rejects: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>>>;
rejects: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>, T>>;
/**
* Unwraps the value of a fulfilled promise so any other matcher can be chained.
* If the promise is rejected the assertion fails.
*/
resolves: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>>>;
resolves: Matchers<Promise<void>> & Inverse<Matchers<Promise<void>, T>>;
};

export interface Matchers<R extends void | Promise<void>> {
type EnsureFunctionLike<T> = T extends (args: any) => any ? T : never;

export interface Matchers<R extends void | Promise<void>, T = unknown> {
/**
* Ensures the last call to a mock function was provided specific args.
*/
lastCalledWith(...expected: Array<unknown>): R;
/**
* Ensure that the last call to a mock function has returned a specified value.
*/
lastReturnedWith(expected: unknown): R;
lastReturnedWith<U extends EnsureFunctionLike<T>>(expected: ReturnType<U>): R;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you are a wizard :)
I'll add this to my PR as well

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks (; Glad you liked it. So much easier to explain with an example.

/**
* Ensure that a mock function is called with specific arguments on an Nth call.
*/
nthCalledWith(nth: number, ...expected: Array<unknown>): R;
/**
* Ensure that the nth call to a mock function has returned a specified value.
*/
nthReturnedWith(nth: number, expected: unknown): R;
nthReturnedWith<U extends EnsureFunctionLike<T>>(
nth: number,
expected: ReturnType<U>,
): R;
/**
* Checks that a value is what you expect. It calls `Object.is` to compare values.
* Don't use `toBe` with floating-point numbers.
Expand Down Expand Up @@ -262,7 +267,9 @@ export interface Matchers<R extends void | Promise<void>> {
* If the last call to the mock function threw an error, then this matcher will fail
* no matter what value you provided as the expected return value.
*/
toHaveLastReturnedWith(expected: unknown): R;
toHaveLastReturnedWith<U extends EnsureFunctionLike<T>>(
expected: ReturnType<U>,
): R;
/**
* Used to check that an object has a `.length` property
* and it is set to a certain numeric value.
Expand All @@ -273,7 +280,10 @@ export interface Matchers<R extends void | Promise<void>> {
* If the nth call to the mock function threw an error, then this matcher will fail
* no matter what value you provided as the expected return value.
*/
toHaveNthReturnedWith(nth: number, expected: unknown): R;
toHaveNthReturnedWith<U extends EnsureFunctionLike<T>>(
nth: number,
expected: ReturnType<U>,
): R;
/**
* Use to check if property at provided reference keyPath exists for an object.
* For checking deeply nested properties in an object you may use dot notation or an array containing
Expand Down Expand Up @@ -303,7 +313,9 @@ export interface Matchers<R extends void | Promise<void>> {
/**
* Use to ensure that a mock function returned a specific value.
*/
toHaveReturnedWith(expected: unknown): R;
toHaveReturnedWith<U extends EnsureFunctionLike<T>>(
expected: ReturnType<U>,
): R;
/**
* Check that a string matches a regular expression.
*/
Expand All @@ -325,7 +337,7 @@ export interface Matchers<R extends void | Promise<void>> {
/**
* Ensure that a mock function has returned a specified value at least once.
*/
toReturnWith(expected: unknown): R;
toReturnWith<U extends EnsureFunctionLike<T>>(expected: ReturnType<U>): R;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe change to this syntax? it works and causes less indirection

Suggested change
toReturnWith<U extends EnsureFunctionLike<T>>(expected: ReturnType<U>): R;
toReturnWith(expected: ReturnType<EnsureFunctionLike<T>>): R;

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. That’s good idea. I was hoping that type argument could allow something like: expect(123).toHaveReturnedWith<() => number>(123). But it doesn’t.

/**
* Use to test that objects have the same types as well as structure.
*/
Expand Down
2 changes: 1 addition & 1 deletion packages/jest-expect/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ type Inverse<Matchers> = {
not: Matchers;
};

type JestMatchers<R extends void | Promise<void>, T> = Matchers<R> &
type JestMatchers<R extends void | Promise<void>, T> = Matchers<R, T> &
SnapshotMatchers<R, T>;

type PromiseMatchers<T = unknown> = {
Expand Down
27 changes: 25 additions & 2 deletions packages/jest-types/__typetests__/expect.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -247,21 +247,44 @@ expectError(expect(jest.fn()).toHaveReturnedTimes(true));
expectError(expect(jest.fn()).toHaveReturnedTimes());

expectType<void>(expect(jest.fn()).toReturnWith('value'));
expectType<void>(expect(jest.fn<() => string>()).toReturnWith('value'));
expectError(expect(jest.fn<() => number>()).toReturnWith('value'));
expectError(expect(123).toReturnWith('value'));
expectError(expect(jest.fn()).toReturnWith());

expectType<void>(expect(jest.fn()).toHaveReturnedWith(123));
expectType<void>(expect(jest.fn<() => number>()).toHaveReturnedWith(123));
expectError(expect(jest.fn<() => string>()).toHaveReturnedWith(123));
expectError(expect(123).toHaveReturnedWith(123));
expectError(expect(jest.fn()).toHaveReturnedWith());

expectType<void>(expect(jest.fn()).lastReturnedWith('value'));
expectType<void>(expect(jest.fn<() => string>()).lastReturnedWith('value'));
expectError(expect(jest.fn<() => number>()).lastReturnedWith('value'));
expectError(expect(123).lastReturnedWith('value'));
expectError(expect(jest.fn()).lastReturnedWith());

expectType<void>(expect(jest.fn()).toHaveLastReturnedWith(123));
expectType<void>(expect(jest.fn<() => number>()).toHaveLastReturnedWith(123));
expectError(expect(jest.fn<() => string>()).toHaveLastReturnedWith(123));
expectError(expect(123).toHaveLastReturnedWith(123));
expectError(expect(jest.fn()).toHaveLastReturnedWith());

expectType<void>(expect(jest.fn()).nthReturnedWith(1, 'value'));
expectType<void>(expect(jest.fn<() => string>()).nthReturnedWith(2, 'value'));
expectError(expect(jest.fn<() => number>()).nthReturnedWith(3, 'value'));
expectError(expect(123).nthReturnedWith(4, 'value'));
expectError(expect(123).nthReturnedWith(5));
expectError(expect(jest.fn()).nthReturnedWith());
expectError(expect(jest.fn()).nthReturnedWith(2));

expectType<void>(expect(jest.fn()).toHaveNthReturnedWith(1, 'value'));
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It works with () => unknown just like before. Infers return value, if there is one. Errors if received is not a function.

expectType<void>(
expect(jest.fn<() => string>()).toHaveNthReturnedWith(2, 'value'),
);
expectError(expect(jest.fn<() => number>()).toHaveNthReturnedWith(3, 'value'));
expectError(expect(123).toHaveNthReturnedWith(4, 'value'));
expectError(expect(123).toHaveNthReturnedWith(5));
expectError(expect(jest.fn()).toHaveNthReturnedWith());
expectError(expect(jest.fn()).toHaveNthReturnedWith(2));

// snapshot matchers

Expand Down