Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: Improve description of optional arguments in ExpectAPI.md #8126

Merged
merged 5 commits into from
Mar 17, 2019

Conversation

pedrottimark
Copy link
Contributor

@pedrottimark pedrottimark commented Mar 14, 2019

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


Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.

You can provide an optional `snapshotName` string argument for the snapshot key, in addition to the concatenated name arguments of containing blocks. Jest also appends `1`, `2`, `3`, and so on to snapshot keys, in case an `it` or `test` block contains multiple snapshot assertions.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link

Codecov Report

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

Impacted file tree graph

@@            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
Copy link
Contributor

jeysal commented Mar 14, 2019

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.

@SimenB SimenB merged commit 8e33622 into jestjs:master Mar 17, 2019
@pedrottimark pedrottimark deleted the optional-arguments-expect branch March 17, 2019 13:58
thymikee added a commit to Brantron/jest that referenced this pull request Mar 19, 2019
* upstream/master: (391 commits)
  more precise circus asyncError types (jestjs#8150)
  Add typeahead watch plugin (jestjs#6449)
  fix: getTimerCount not taking immediates and ticks into account (jestjs#8139)
  website: add an additional filter predicate to backers (jestjs#7286)
  [🔥] Revised README (jestjs#8076)
  [jest-each] Fix test function type (jestjs#8145)
  chore: improve bug template labels for easier maintenance (jestjs#8141)
  Add documentation related to auto-mocking (jestjs#8099)
  Add support for bigint to pretty-format (jestjs#8138)
  Revert "Add fuzzing based tests in Jest (jestjs#8012)"
  chore: remove console.log
  chore: Improve description of optional arguments in ExpectAPI.md (jestjs#8126)
  Add fuzzing based tests in Jest (jestjs#8012)
  Move @types/node to the root package.json (jestjs#8129)
  chore: use property initializer syntax (jestjs#8117)
  chore: delete flow types from the repo (jestjs#8061)
  Move changelog entry to the proper version (jestjs#8115)
  Release 24.5.0
  Expose throwOnModuleCollision (jestjs#8113)
  add matchers to expect type (jestjs#8093)
  ...
@github-actions
Copy link

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.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators May 11, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Snapshots for strings are sometimes being transformed into objects/arrays
6 participants