👹 jest-extended-snapshot
Additional Jest matchers for snapshot testing.
Requires Jest version >= 23.
Why?
If you find yourself in a scenario where you want to add tests after code has been written, you might want to use Jest snapshots.
A typical scenario is working with legacy code: it has no test, but you need to change/fix it. You should set up a test harness first, to ensure there would be no regression. Jest snapshots make this job easier.
This lib adds convenient matchers to work in such scenario.
Approval testing with Jest snapshots
Consider the previous example: you don’t know what a piece of code precisely does, but you don't want to break existing behavior. One approach to use in this situation is called "Approval testing".
It can get you test coverage quickly, without having to understand the code.
Unit testing asserts can be difficult to use. Approval tests simplify this by taking a snapshot of the results, and confirming that they have not changed.
Further information: http://approvaltests.com/
Installation
With npm:
npm install --save-dev jest-extended-snapshot
With yarn:
yarn add -D jest-extended-snapshot
Set up
Jest 23
Add jest-extended-snapshot
to your Jest setupTestFrameworkScriptFile
configuration. See Jest website for more information.
"jest": {
"setupTestFrameworkScriptFile": "jest-extended-snapshot"
}
If you are already using another test framework, like jest-extended, you should create a test setup file to require each of the frameworks you are using.
For example:
// ./test-setup.js
require("jest-extended-snapshot");
require("any other test framework libraries you are using");
Then in your Jest config:
"jest": {
"setupTestFrameworkScriptFile": "./test-setup.js"
}
Jest version >= 24
Add jest-extended-snapshot
to your setupFilesAfterEnv
array in the Jest configuration. See Jest website for more information.
"jest": {
"setupFilesAfterEnv": ["jest-extended-snapshot"]
}
TypeScript
If your editor does not recognise the custom jest-extended-snapshot
matchers, add a global.d.ts
file to your project with:
import "jest-extended-snapshot";
List of additional matchers (API)
.toVerifyAllCombinations([args])
Test all combinations of given parameters to the function under test, and match against snapshot.
Usage:
expect(myFunction).toVerifyAllCombinations([args]);
Example
function myFunction(aNumber, aString) {
if (aNumber > 0) {
return `${aString} #${aNumber}`;
}
if (aString === "foo") {
return `${aNumber} bar`;
}
return "This is twisted…";
}
it("should continue working as before", () => {
expect(myFunction).toVerifyAllCombinations([1, -1], ["random", "foo"]);
});
Will produce following snapshot:
// Jest Snapshot v1, https://goo.gl/fbAQLP
exports[`should continue working as before 1`] = `
Object {
"-1,foo": "-1 bar",
"-1,random": "This is twisted…",
"1,foo": "foo #1",
"1,random": "random #1",
}
`;
How to use best
- Determine the inputs you could combine to test your code
- Determine the output you could make a snapshot from
- Use test coverage to determine which parts are not covered yet
- Augment your inputs combination until you cover all of the code
- Perform little mutations in your covered code to check the quality of your snapshot
- Augment your inputs combination until there is no way you can add mutations without the test failing
- In the end, you got a snapshot of what your code does. And you can start refactoring with confidence
List of helpers
range(start, end)
/ range(end)
Generate a list of numbers from start
to end
. Syntactic sugar to generate exhaustive combinations of number inputs.
Defaults start
to 0
if called with a single parameter.
import { range } from "jest-extended-snapshot";
// All are equivalent
expect(myFunction).toVerifyAllCombinations([0, 1, 2, 3, 4], ["foo"]);
expect(myFunction).toVerifyAllCombinations(range(0, 4), ["foo"]);
expect(myFunction).toVerifyAllCombinations(range(4), ["foo"]);