docs: example how to verify call arguments through asymmetric matchers

[skyboyer]

Cross-reference from toHaveBeenCalledWith to asymmetric matchers like expect.anything() or expect.objectContaining() for better clarity

Fixes #11752

Summary

Docs give an example of usage expect.anything() and other asymmetric matchers when defining that matchers. However, people who never used them, will not probably skim the doc page(which is - yes, for a reason - but long). Up to my experience with my colleagues, ~50% knows about using asymmetric matchers for arguments validation and start to use expect(mockFn.mock.calls[0][1]).toEqual(someLiteral) instead.

So mentioning that for toHaveBeenCalledWith I also target people who have never used asymmetric matchers before. I know such developers, however I know nobody who never used toHaveBeen...Called...().

Decided not to put the same block into toHaveBeenLastCalledWith and toHaveBeenNthCalledWith again.

Test plan

[facebook-github-bot]

Hi @skyboyer!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

[skyboyer]

I'm willing to apply the same changes to versioned_docs however I'd like to get approval on wording/phrasing first.

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

[skyboyer]

@mrazauskas it might be pretty helpful if people get directly into that particular methods by searching/direct link as a first experience wiht Jest docs. But I'm afraid if we put it into every relevant section, it might be ignored by a reader. Or am I overthinking?

Regarding making example shorter, if there was section on Asymmetric matcher, then yes, would be much easier to use, say, just expect.stringContaining for a demonstration and to give a link to that section. But until then, using different matchers in the same example I try to give understanding what is "asymmetric matcher" by an example, so a newcomer does not need to search a term across the docs. What do you think, does my patch reach this goal or not really? :)

Finally, as for introducing sections - this would be the best way, imo, but definitely more time-consuming(making changes, discussing, getting approvals).

[SimenB]

The asymmetric matchers are already grouped - splitting of into its own section seems reasonable to me? Shouldn't be too big of a change.

[mrazauskas]

Finally, as for introducing sections - this would be the best way, imo, but definitely more time-consuming(making changes, discussing, getting approvals).

See #13791

[skyboyer]

obsolete since #13791 added a lot of examples into the docs

[github-actions[bot]]

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.