From 80166c6d5a504b808a8ea8df9947bcb8e7144d3a Mon Sep 17 00:00:00 2001 From: Kevin McLoughlin Date: Mon, 30 Apr 2018 18:36:00 -0400 Subject: [PATCH] Add a 'best practices' section to the Snapshot Testing Guide: Issue: https://github.com/facebook/jest/issues/5812 Tools get even better when it's clear how they're meant to be used. Created a 'best practices' section where patterns that are known to improve the usefulness of Jest's snapshot feature can be explained for the community's benefit. --- .../version-22.3/SnapshotTesting.md | 28 +++++++++++++------ 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/website/versioned_docs/version-22.3/SnapshotTesting.md b/website/versioned_docs/version-22.3/SnapshotTesting.md index 33b1ae2f7c7d..ae8bfe65ba0f 100644 --- a/website/versioned_docs/version-22.3/SnapshotTesting.md +++ b/website/versioned_docs/version-22.3/SnapshotTesting.md @@ -136,7 +136,22 @@ From here you can choose to update that snapshot or skip to the next: ![](/jest/img/content/interactiveSnapshotUpdate.gif) -### Tests Should Be Deterministic +## Best Practices + +Snapshots are a fantastic tool for identifying unexpected interface changes within your application – whether that interface is a UI, logs, or error messages; however, they're not a cure-all, and, as with any testing strategy, there are some best-practices you should be aware of, and guidelines you should follow, in order to use them effectively. + +### 1. Treat Snapshots As First-Class Citizens + +Commit snapshots and review them as part of your regular code review process. This implies treating snapshots as you would any other type of test, or code for that matter, in your project. + +Ensure that your snapshots are _very_ readable by keeping them focused, short, and using tools that enforce these stylistic conventions. + +As mentioned previously, Jest uses +[pretty-format](https://github.com/facebook/jest/tree/master/packages/pretty-format) to make snapshots human-readable, but you may find it useful to introduce additional tools, like [`eslint-plugin-jest`](https://github.com/jest-community/eslint-plugin-jest/blob/master/docs/rules/no-large-snapshots.md) with its `'no-large-snapshots'` option, and [`snapshot-diff`](https://github.com/jest-community/snapshot-diff) with its component snapshot comparison feature, to promote committing short, focused assertions. + +The aim here is to avoid the dangerous habits of glossing over snapshots in pull requests, and simply regenerating snapshots when test suites fail instead of examining the root causes of their failure. + +### 2. Tests Should Be Deterministic Your tests should be deterministic. That is, running the same tests multiple times on a component that has not changed should produce the same results every @@ -158,16 +173,11 @@ Now, every time the snapshot test case runs, `Date.now()` will return `1482363367071` consistently. This will result in the same snapshot being generated for this component regardless of when the test is run. -### Snapshots are not written automatically on Continuous Integration systems (CI) +## Frequently Asked Questions -As of Jest 20, snapshots in Jest are not automatically written when Jest is run -in a CI system without explicitly passing `--updateSnapshot`. It is expected -that all snapshots are part of the code that is run on CI and since new -snapshots automatically pass, they should not pass a test run on a CI system. It -is recommended to always commit all snapshots and to keep them in version -control. +### Are snapshots written automatically on Continuous Integration (CI) systems? -## Frequently Asked Questions +No, as of Jest 20, snapshots in Jest are not automatically written when Jest is run in a CI system without explicitly passing `--updateSnapshot`. It is expected that all snapshots are part of the code that is run on CI and since new snapshots automatically pass, they should not pass a test run on a CI system. It is recommended to always commit all snapshots and to keep them in version control. ### Should snapshot files be committed?