Add a calledOnceWithMatch assertion

[richthegeek]

Purpose

This adds an assertion which combines calledOnce and calledWithMatch into calledOnceWithMatch.

Background (Problem in detail)

This is a common pattern in tests that I write:

  sinon.assert.calledOnce(stub);
  sinon.assert.calledWithMatch(stub, arg1, arg2);

It would be great to only need write:

  sinon.assert.calledOnceWithMatch(stub, arg1, arg2);

It seems like uneven coverage to combine calledOnce + calledWithExactly whilst not covering this.

However, I can see that there is a potential for temptation to add too much sugar - no-one wants a combinatorial explosion! Many libraries solve this with something like sinon.assert.calledOnce(stub).withMatch(arg1, arg2) but that's not a discussion for this PR!

Testing

I was looking through the test files and wasn't entirely sure what coverage would be appropriate here - I'm happy to essentially duplicate the calledOnceWithMatch testing if that is sufficient coverage and validation, but it feels incomplete.

Please let me know what you think.

How to verify - mandatory

1. Check out this branch
2. npm install
3. npm test

Checklist for author

• npm run lint passes
• References to standard library functions are cached.

[mroderick]

Thank you for the pull request!

I agree, it seems silly not to have calledOnceWithMatch when calledOnceWithExactly exists.

I'm in favour of duplication in tests, as that makes each set easy to understand (and throw out) ... as opposed to really DRY tests, that require a lot of refactoring every time there's an expansion of the API. Please go ahead with the tests 🚀

@mantoni we should synchronise the list of assertions in @sinonjs/referee-sinon once this is merged, so the new assertion can be used as referee.assert.calledOnceWithMatch.

[mantoni]

I have a need for this sometimes as well. Thank you! 🙏👍

[richthegeek]

I've added testing based on calledOnceWithExactly, which at least confirms it works. I changed one slightly to specifically test the "match" part. I'm happy for this to be merged 👍

[mantoni]

@richthegeek Regarding your suggestion to compose assertions instead of adding too much suggar, I'd like to highlight that this is a possible alternative that works today:

const spy = sinon.spy();

spy('some test');

sinon.assert.calledWith(spy, sinon.match('test'));

[richthegeek]

@matoni great 👍

I meant mostly that having calledTwiceWithExactly calledThriceWithExactly calledThriceWithMatch etc would become a bit silly and unwieldy... and so even adding calledOnceWithMatch could be crossing that line for some people.

[mantoni]

Released in v9.1.0. Thank you ❤️