chore: Improve description of optional arguments in ExpectAPI.md

[pedrottimark]

Summary

Fixes #8059

We fix the doc now, and then at next major version will make breaking change to throw new errors when toMatchSnapshot has unexpected combinations of arguments.

For example, if first argument is object, but second argument is not object. /cc @morungos

• Append ? to optional arguments in headings.
• Rewrite corresponding prose so optional always occurs.

For local test of website to make sure ? didn’t break links, I had to make corresponding changes to the versioned doc, but I forget if I needed to commit that change, or is it is automatic?

matcher	optional arguments
toBeCloseTo	numDigits
toHaveProperty	value
toMatchSnapshot	propertyMatchers and snapshotName
toMatchInlineSnapshot	propertyMatchers
toThrow	error
toThrowErrorMatchingSnapshot	snapshotName

Two existing link anchors changed where arguments were missing:

• #tothrowerrormatchingsnapshot
• #tothrowerrormatchinginlinesnapshot

Here are proposed sentences to help you review for clear meaning and consistent grammar:

• The optional numDigits argument has default value 2 which means the criterion is Math.abs(expected - received) < 0.005 (that is, 10 ** -2 / 2).
• You can provide an optional value argument to compare the received property value (recursively for all properties of object instances, also known as deep equality, like the toEqual matcher).
• You can provide an optional propertyMatchers object argument, which has asymmetric matchers as values of a subset of expected properties, if the received value will be an object instance. It is like toMatchObject with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
• EDITED: You can provide an optional snapshotName string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single it or test block. Jest sorts snapshots by key in the corresponding .snap file.
• ADDED: Jest adds the inlineSnapshot string argument to the matcher in the test file (instead of an external .snap file) the first time that the test runs.
• You can provide an optional argument to test that a specific error is thrown:

Residue: It’s hard to say if inlineSnapshot argument is optional or required. The tester (usually) doesn’t write it, but Jest does provide it when assertion passes the first time.

Test plan

yarn lint:md passed

[thymikee]

I find this description convoluted around "snapshot key" and "nam arguments of containing blocks". Can we make it simpler?

[pedrottimark]

Yes, thank you. What do you think of this rewrite?

You can provide an optional snapshotName string argument for the snapshot key. It follows the concatenated name arguments of containing blocks and precedes the final number (that Jest appends in case an it or test block contains multiple snapshot assertions).

I deleted the comment that I wrote in the main thread by mistake.

[pedrottimark]

s/multiple snapshot assertions/more than one snapshot assertion/

[thymikee]

How about:

You can provide an optional snapshotName string argument that will be appended to the corresponding test title in .snap file, followed by a number that Jest appends to differentiate between snapshots created during single it or test block.

(the number is always appended)

[thymikee]

Oh btw, can you mention that snapshots are sorted in alphabetical order for stability? I don't see this mentioned anywhere in the docs

[codecov-io]

Codecov Report

Merging #8126 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #8126      +/-   ##
==========================================
- Coverage   62.43%   62.42%   -0.01%     
==========================================
  Files         264      264              
  Lines       10368    10368              
  Branches     2515     2515              
==========================================
- Hits         6473     6472       -1     
  Misses       3318     3318              
- Partials      577      578       +1

Impacted Files	Coverage Δ
packages/jest-core/src/SearchSource.ts	56.84% <0%> (-1.06%)	⬇️

---

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 4f06ee4...2fdb39f. Read the comment docs.

[jeysal]

It’s hard to say if inlineSnapshot argument is optional or required.

IMO it's optional. The matcher won't throw an error if it's not there (just like toMatchSnapshot() won't throw if a snapshot file is not there), so it was a valid call, one that causes Jest to write the snapshot by modifying that call in the test file.

Also avoids the non-optional argument after optional argument thing which looks weird, although I guess it's still slightly confusing that any one of the arguments can be omitted and the other one will be used based on its type.

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