This is a living document of testing standards to use across the org. As issues are found and addressed, learnings will be added to this doc so that everyone can benefit.

Unit testing

Language/Framework-specific Guidelines

JavaScript/React

When writing unit tests in JavaScript, the test files should be located in the same directory, and share the same name, as the files they are testing, rather than putting all tests in a separate directory structure. For example, if a React component is defined in src/common/components/my-component.jsx, its tests should be in src/common/components/my-components.test.js. Note that the only difference in the paths is the file extension (.jsx vs. .test.js). Organizing tests this way allows the tests to be found much more easily and makes them more resilient to refactoring if files are moved around.

Snapshot Testing

For React, unit tests should utilize Snapshot tests as much as possible for validating the structure of HTML components. In general, these tests should capture all of the non-interactive features of a component, such as text, className, etc. Most changes to these types of features are stylistic and subjective in nature, rather than being directly tied to a functional requirement, so snapshot tests allow developers to quickly identify any unwanted changes or update the snapshots for acceptable changes. Non-static or interactive features, such as login, onClick scripts, menu navigation, etc. should be tested with more traditional unit tests. For more information about snapshot tests, see the link above, or see this blog post for more details about when it is appropriate to use snapshot tests.

Updating snapshots

When a snapshot test fails, Jest prints out a diff between the generated HTML and the expected HTML. After reviewing all snapshots and addressing any unwanted changes, you can accept all remaining changes and update the snapshots by running npx jest -u. After doing so, make sure to double-check the changes to the snapshot files in git before pushing your changes.