[jest] Add new structure and matchers related to mock results.

[UselessPickles]

Please fill in this template.

• Use a meaningful title for the pull request. Include the name of the package modified.
• Test the change in your own code. (Compile and run.)
• Add or edit tests to reflect the change. (Run with npm test.)
• Follow the advice from the readme.
• Avoid common mistakes.
• Run npm run lint package-name (or tsc if no tslint.json is present).

Select one of these and delete the others:

If changing an existing definition:

• Provide a URL to documentation or source code which provides context for the suggested changes: Series of PRs related to this change (note: structure changed a couple times throughout these PRs):

• Enhance function mocks to expose a list of returned values. jestjs/jest#5752
• [jest-mock] Track thrown errors in MockFunctionState jestjs/jest#5764
• Add mock return matchers jestjs/jest#5879
• [expect] Improve mock "return" matchers to properly handle calls that throw jestjs/jest#6172

• Increase the version number in the header if appropriate.
• If you are making substantial changes, consider adding a tslint.json containing { "extends": "dtslint/dt.json" }.

[typescript-bot]

@UselessPickles Thank you for submitting this PR!

🔔 @NoHomey @jwbay @asvetliakov @alexjoverm @epicallan @ikatyang @wsmd @JamieMason @douglasduteil @AhnpGit @JoshuaKGoldberg @bradleyayers - please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

If no reviewer appears after a week, a DefinitelyTyped maintainer will review the PR instead.

[JoshuaKGoldberg]

Changes look good! Please add some unit tests to verify we don't break this later on.

Edit: oh, and don't forget to add your name to the list of collaborators. Wouldn't want you to miss out on getting pinged for changes 😉

[JoshuaKGoldberg]

Looks like a dup of #26236 😊 race condition in an exciting feature add.

[ahnpnl]

Let's combine all the necessary changes here 😀

[typescript-bot]

@UselessPickles One or more reviewers has requested changes. Please address their comments. I'll be back once they sign off or you've pushed new commits or comments. Thank you!

[niedzielski]

I'm stoked for this change to land! Don't forget toStrictEqual()!

https://github.com/DefinitelyTyped/DefinitelyTyped/pull/26236/files
https://facebook.github.io/jest/blog/2018/05/29/jest-23-blazing-fast-delightful-testing.html

[ahnpnl]

I think we can make another PR for toStrictEqual and toMatchSnapshot 👌since @UselessPickles is only familiar with the matchers he has been using.

[UselessPickles]

@JoshuaKGoldberg I can't quite comprehend the current organization of the unit tests to figure out how best to add unit tests. I'm particularly confused by the fact that the unit tests appear to be run-time functional tests, rather than compile-time dtslint tests.

As far as adding everything else new to Jest 23, I'm not comfortable taking on that responsibility. This PR only includes the stuff that I'm quite familiar with because I was involved in implementing it.

[JoshuaKGoldberg]

Oh sure, in that case let's get a partially complete update in and then I can work on the rest of it.

You can see an example of unit tests for approximately these changes in https://github.com/DefinitelyTyped/DefinitelyTyped/pull/26236/files#diff-830a7c9e24903b49e811209b6cd30c58. If it helps, they are compile-time dtslint tests: the output from the test .ts files is ignored.

If you don't have the time to get around to the tests, that works too! I'm sure @ahnpnl and/or I can make an updated or third PR with a union of all the proposed changes.

[UselessPickles]

I may have some time to look at unit tests tonight.

[typescript-bot]

@UselessPickles I haven't seen anything from you in a while and this PR currently has problems that prevent it from being merged. The PR will be closed tomorrow if there aren't new commits to fix the issues.

[UselessPickles]

I looked at the tests again. There is no discernible pattern/organization to me.

They seem to be mostly written as runtime behavior unit tests (possibly copy/pasted from the jest project?) rather than compile time type tests. They are not dtslint tests that can actually verify types of anything. It can only fail to compile if types are not assignable (which does not verify the exact type), typos in method names, etc.

There are no existing tests for other matchers similar to the ones that I'm adding here, and therefore no obvious place to add the new tests or pattern to follow.

I could slap some stuff in there that doesn't really fit anywhere within the existing tests, but I am not comfortable putting my name on something when I know I don't understand if I'm properly following existing patterns (of which I cannot even identify).

I'm more than happy to contribute updates to the type definitions themselves that correspond to changes I contribute to Jest itself, but the existing tests really need to be reworked as type tests (using dtslint) and reorganized in a way that makes them more easily maintainable. I do not understand the existing tests well enough to update them.

[typescript-bot]

@UselessPickles To keep things tidy, we have to close PRs that aren't mergeable but don't have activity from their author. No worries, though - please open a new PR if you'd like to continue with this change. Thank you!

[JoshuaKGoldberg]

I can send a separate PR that adds tests onto this. Thanks for the feature add!