Add mock return matchers

[rickhanlonii]

Summary

[Edited] Adds spy matchers for the returnValues supported added in #5752 which pair with the call matchers

Closes #3821

Test plan

• Added Unit Tests

Docs

Why Core

As is the case for most matchers, this could be a custom matcher. I think it belongs in core because:

• It matches on a core internal, returnValue, so helps in discoverability for custom matchers
• It adds parity with sinon spy.returned

[mattphillips]

Nice @rickhanlonii I really like the look of this matcher! Do you think we would want to handle the order the value was returned too? So a mock can return multiple values i.e.

test(`passes with mutliple calls`, () => {
  const fn = jest.fn(a => a * 2);
  fn(1);
  fn(2);
  fn(3);

  expect(fn).toReturn(2);
  expect(fn).toReturn(4);
  expect(fn).toReturn(6);
});

or with mockReturnValueOnce and mockReturnValue

myMock
  .mockReturnValueOnce(10)
  .mockReturnValueOnce('x')
  .mockReturnValue(true);

I think it might be good to assert that the mock returned the correct value at the correct position: first, second, N. This would be similar to nthCalledWith

What do you think?

[SimenB]

I'd like a "but it returned: " for failures pretty printing all values

[rickhanlonii]

@mattphillips good thinking - I see two options, curious what your thoughts are (ditto @SimenB)

Option 1: Mirror .toBeCalledWith

To mirror .toBeCalledWith, we would add (along with the aliases):

• toReturn
• toReturnLast
• toReturnTimes
• toNthReturn

Pros

• Consistency
• Flexibility
• A matcher for every use case

Cons

• A ton of new matchers

Option two: toReturn

Instead, we could have toReturn accept all of the values returned, in order:

test(`passes with multiple calls`, () => {
  const fn = jest.fn(a => a * 2);
  fn(1);
  fn(2);
  fn(3);

  expect(fn).toReturn(2, 4, 6);
});

Pros

• Only one new matcher

Cons

• Have to specify all of the returned values, in order

[rickhanlonii]

Keep in mind we also added thrownErrors to the spies so we're probably going to want core matchers to check that as well, meaning whatever we choose here will probably be doubled

[SimenB]

@cpojer thoughts?

[cpojer]

I like it, mirroring toBeCalledWith seems the most sensible approach.

[SimenB]

I can get down with matching toBeCalledWith, any extra matchers on top of that can go into jest-extended or some such.

Quickly to answer "Why core":

It matches on a core internal, returnValue, so helps in discoverability for custom matchers

This is meh, IMO. It was added to core to enable the use case, not to force matchers being added. We should be better at pointing to custom matchers listed in awesome-jest perhaps.

It adds parity with sinon spy.returned

That's a better point - being able to cover the use cases of tools people are using already out of the box is Jest's biggest strength (in addition to the crazy awesome watch mode).

[mattphillips]

I agree with @SimenB and @cpojer I think we should keep parity with toBeCalledWith

@SimenB how do you think we should point to awesome-jest matchers more? Perhaps we should update our issue template to point people over there to find community solutions?

[SimenB]

If the template gets to be too large, people ignore it (already an issue). But saying something like "if you want a new matcher, please see x" in the template might help?

[SimenB]

@rickhanlonii ping 🙂

A quick rebase shuold fix CI as well

[rickhanlonii]

Ah yes, sorry - I'm working on mirroring toBeCalledWith, will wrap up this week

[rickhanlonii]

Update: still needs docs, but the matchers are pushed and ready for review

Here's an overview of the returnValue matchers and aliases added paired with their calls matcher:

Matchers

called	returned
lastCalledWith	lastReturnedWith
nthCalledWith	nthReturnedWith
toBeCalled	toReturn
toBeCalledWith	toReturnWith
toBeCalledTimes	toReturnTimes

Aliases

called	returned
toHaveBeenLastCalledWith	toHaveLastReturnedWith
toHaveBeenNthCalledWith	toHaveNthReturnedWith
toHaveBeenCalled	toHaveReturned
toHaveBeenLastCalledWith	toHaveLastReturnedWith
toHaveBeenCalledTimes	toHaveReturnedTimes

[rickhanlonii]

@cpojer I blamed the spy switching we're doing here to you - is this only to support jasmine spies or am I missing something? If it's just jasmine, I think we can remove this switch in the new returnValues matchers since jasmine does not store those values

[cpojer]

Yes, this is just for Jasmine.

[codecov-io]

Codecov Report

Merging #5879 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff           @@
##           master   #5879   +/-   ##
======================================
  Coverage    64.1%   64.1%           
======================================
  Files         217     217           
  Lines        8335    8335           
  Branches        4       4           
======================================
  Hits         5343    5343           
  Misses       2991    2991           
  Partials        1       1

---

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 9850275...e8a669a. Read the comment docs.

[SimenB]

Should these use string templates?

[SimenB]

Should we call it "spy"?

[SimenB]

Should doc every new matcher, right?

[SimenB]

Update: still needs docs

Oh, ignore me then :D

[rickhanlonii]

Docs updated, this is ready for final review

[rickhanlonii]

Updated OP with a screenshot of the new docs 🤙

[SimenB]

is this correct?

[SimenB]

ref the title being toHaveLastReturnedWith works when not called

[rickhanlonii]

Nice find - fixed

[SimenB]

should this say "but it did" or something?

[rickhanlonii]

Yeah, updated

[SimenB]

I added 2 inline comments, one being what I believe is a bug, the pother a question.

Other than that, I just think this is missing a changelog entry 🙂

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