New matchers: toHaveBeenCalledOnce and toHaveBeenCalledOnceWith

[amercier]

I think it would be nice to add the following matchers for Mock:

toHaveBeenCalledOnce

const mock = jest.fn();
// ...
expect(mock).toHaveBeenCalledOnce();

that would be equivalent to:

const mock = jest.fn();
// ...
expect(mock).toHaveBeenCalledTimes(1);

toHaveBeenCalledOnceWith

const mock = jest.fn();
// ...
expect(mock).toHaveBeenCalledOnceWith('foo', 'bar');

that would be equivalent to:

const mock = jest.fn();
// ...
expect(mock).toHaveBeenCalledTimes(1);
expect(mock).toHaveBeenLastCalledWith('foo', 'bar');

Rationale

I find myself regularly writing tests with only one call per mock. Especially while writing unit tests, where I prefer writing many small, atomic tests, rather than one large test for all cases.

[benjaminkay93]

This sounds like a really good matcher and i would find it helpful myself :)

[benjaminkay93]

if nothing else im happy to raise a pr for this

[julianjurai]

That would be a nice addition! There is something similar but not as semantic :

const mock = jest.fn();
expect(mock).toHaveBeenNthCalledWith(1, 'foo');

[mattphillips]

Sounds great! Feel free to send a PR with this, just drop a note here if you are working on it :smile:

[benjaminkay93]

Ive got a branch locally with a toHaveBeenCalledOnce matcher, it was queit straightforward, however the toHaveBeenCalledOnceWith is causing my brain issues, should we use === equality on objects or == equality on them?

[mattphillips]

@benjaminkay93 I think we probably want to do deep equality on them you can use the equals util to compare two objects deeply or the contains util to deeply check if an array contains an object

[benjaminkay93]

Sweet thank you @mattphillips, big help

[SimenB]

toHaveBeenCalledOnce added via #274, still missing toHaveBeenCalledOnceWith if anyone is up for it 🙂

[theryansmee]

@SimenB - I'll take a look at toHaveBeenCalledOnceWith 😊