👹 jest-extended-snapshot

Additional Jest matchers for snapshot testing.

📝 Read the blog post.

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

1. Determine the inputs you could combine to test your code
2. Determine the output you could make a snapshot from
3. Use test coverage to determine which parts are not covered yet
4. Augment your inputs combination until you cover all of the code
5. Perform little mutations in your covered code to check the quality of your snapshot
6. Augment your inputs combination until there is no way you can add mutations without the test failing
7. In the end, you got a snapshot of what your code does. And you can start refactoring with confidence

👌 I recommend you watch this video of Emily Bache, applying this over the Gilded Rose refactoring kata (in Java): https://youtu.be/zyM2Ep28ED8

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"]);