snap-shot

Jest-like snapshot feature for the rest of us + data-driven testing!

snap-shot-jest-test - for testing snap-shot against Jest runner (React + JSX)

snap-shot-modules-test - for testing against transpiled ES6 modules

snap-shot-vue-test - for testing snap-shot inside Jest + Vue.js project

snap-shot-jsdom-test - for testing snap-shot using mock DOM adapter and element serialization

snap-shot-ava-test - for testing how snap-shot works with Ava test framework

Why

Read Snapshot testing the hard way

I like Jest snapshot idea and want it without the rest of Jest testing framework. This module is JUST a single assertion method to be used in BDD frameworks (Mocha, Jasmine)

Also, I really really really wanted to keep API as simple and as "smart" as possible. Thus snap-shot tries to find the surrounding unit test name by inspecting its call site (using stack-sites or callsites) and parsing AST of the spec file (using falafel).

Snapshot values are compared using variable-diff (objects) and disparity (multi line strings). See images/README.md for screenshots.

This function also includes data-driven testing mode, similar to sazerac, see Data-driven testing section below.

Example

Install: npm install --save-dev snap-shot

const snapshot = require('snap-shot')
// in ES6 code use
import snapshot from 'snap-shot'
it('is 42', () => {
  snapshot(42)
})

Run it first time with mocha spec.js. This will create snapshots JSON values file inside __snapshots__/spec.js.snap-shot. In general this file should close to Jest format, but the file extension is different to avoid clashing with Jest persistence logic.

$ mocha spec.js
$ cat __snapshots__/spec.js.snap-shot
module.exports[`is 42 1`] = 42

Now modify the spec.js file

const snapshot = require('snap-shot')
it('is 42', () => {
  snapshot(80)
})

$ mocha spec.js
1) is 42:
    Error: expected 42 got 80

Note snap-shot does not store or handle undefined values, since they are likely an edge case. If you disagree, open an issue please.

Note All values are saved as JSON, thus non-serializable values, like functions are stripped before comparison.

Promises

For asynchronous code, please have a function inside the spec before calling snap-shot or let snap-shot wrap the promise.

it('promise to function', () => {
  return Promise.resolve(20)
    .then(data => snapshot(data))
})

it('snap-shot can wrap promise', () => {
  return snapshot(Promise.resolve('value'))
})

// does NOT work
it('promise to snapshot', () => {
  return Promise.resolve(20)
    .then(snapshot)
})

In the last test, the stack trace from snap-shot cannot get any parent information, thus it cannot find the unit test.

See src/async-spec.js

Jest

You can use this assertion inside Jest tests too.

const snapshot = require('snap-shot')
test('my test', () => {
  snapshot(myValue)
})

Ava

Should work (including async / await syntax), see snap-shot-ava-test for the current status.

import test from 'ava'
import snapshot from 'snap-shot'
test('concat strings', t => {
  snapshot('f' + 'oo')
})

DOM testing (via jsdom and jsdom-global)

You can easily mock DOM and use snapshots (either in text or JSON format), see snap-shot-jsdom-test project.

React + JSX

If snap-shot finds .babelrc inside the current working folder, it will try transpiling loaded files using babel-core API. This makes it useful for testing React code. For full example see Link.test.js

Showing snapshots when saving

If you just want to see what a new schema would be, without saving it, run the tests with DRY=1 npm test option.

If you want to see the schema and save it, run the tests with SHOW=1 npm test

$ SHOW=1 npm test
saving snapshot "spec name" for file ./src/valid-message-spec.js
{ firstLine: 'break(log): new log format',
  type: 'major',
  scope: 'log',
  subject: 'new log format' 
}

Update snapshots

To update all saved values, run with UPDATE=1 environment variable.

$ UPDATE=1 mocha spec.js

To update snapshot inside a single test function, use second argument

const snapshot = require('snap-shot')
it('is 42', () => {
  snapshot(80, true)
})
// snapshot file now has {"is 42": 80)

You can also update a single or several tests when running Mocha by filtering the tests using grep feature.

$ UPDATE=1 mocha -g "test name pattern" *-spec.js

CI

Note most CIs (like Travis, Circle, GitLabCI) define environment variable CI, which we take into consideration as well. It makes no sense to allow saving snapshot on CI, thus if the process.env.CI is set, the snapshot MUST exist on disk.

Format

There is no magic in formatting snapshots. Just use any function or compose with snapshot before comparing. Both choices work

const snapshot = require('snap-shot')
it('compares just keys', () => {
  const o = {
    foo: Math.random(),
    bar: Math.random()
  }
  snapshot(Object.keys(o))
})
// snapshot will be something like
/*
exports['compares just keys 1'] = [
  "foo",
  "bar"
]
*/

const compose = (f, g) => x => f(g(x))
const upperCase = x => x.toUpperCase()
const upValue = compose(snapshot, upperCase)

it('compares upper case string', () => {
  upValue('foo')
})
/*
exports['compares upper case string 1'] = "FOO"
*/

See src/format-spec.js

General advice

Simple is better. Format the data and then call snapshot.

it('works', () => {
  const domNode = ...
  const structure = formatHtml(domNode)
  snapshot(structure)
})

Tests with dynamic names

Sometimes tests are generated dynamically without hardcoded names. In this case SHA256 of the test callback function is used to find its value.

// this still works
const testName = 'variable test name (value 30)'
const value = 30
it(testName, () => {
  // this is a test without hard coded name
  snapshot(value)
})
// snapshot file will have something like
// exports['465fb... 1'] = 30

The best strategy in this case is to use meaningful name for the callback function

const testName = 'variable test name (value 30)'
const value = 30
it(testName, function is30() {
  snapshot(value)
})
// snapshot file will have something like
// exports['is30 1'] = 30

See src/unknown-name-spec.js

Multiple snapshots

A single test can have multiple snapshots.

it('handles multiple snapshots', () => {
  snapshot(1)
  snapshot(2)
})
it('uses counter of snapshot calls', () => {
  for (let k = 0; k < 10; k += 1) {
    snapshot(`snap ${k}`)
  }
})

See src/multiple-spec.js

Data-driven testing

Writing multiple input / output pairs for a function under test quickly becomes tedious. Luckily, you can test a function by providing multiple inputs and a single snapshot of function's behavior will be saved.

// checks if n is prime
const isPrime = n => ...
it('tests prime', () => {
  snapshot(isPrime, 1, 2, 3, 4, 5, 6, 7, 8, 9)
})

The saved snapshot file will have clear mapping between given input and produced result

// snapshot file
exports['tests prime 1'] = {
  "name": "isPrime",
  "behavior": [
    {
      "given": 1,
      "expect": false
    },
    {
      "given": 2,
      "expect": true
    },
    {
      "given": 3,
      "expect": true
    },
    {
      "given": 4,
      "expect": false
    },
    {
      "given": 5,
      "expect": true
    },
    ...
  ]
}

You can also test functions that expect multiple arguments by providing arrays of inputs.

const add = (a, b) => a + b
it('checks behavior of binary function add', () => {
  snapshot(add, [1, 2], [2, 2], [-5, 5], [10, 11])
})

Again, the snapshot file gives clear picture of the add behavior

// snapshot file
exports['checks behavior of binary function add 1'] = {
  "name": "add",
  "behavior": [
    {
      "given": [
        1,
        2
      ],
      "expect": 3
    },
    {
      "given": [
        2,
        2
      ],
      "expect": 4
    },
    {
      "given": [
        -5,
        5
      ],
      "expect": 0
    },
    {
      "given": [
        10,
        11
      ],
      "expect": 21
    }
  ]
}

See src/data-driven-spec.js for more examples.

Debugging

Run with DEBUG=snap-shot environment variable

$ DEBUG=snap-shot mocha spec.js

If you want to see messages only when new values are stored use

$ DEBUG=save mocha spec.js
save Saved for "is 42 1" snapshot 42

There are special projects that are setup to test this code in isolation as dependent projects, see above.

Related

• chai-jest-snapshot if you are using Chai
• schema-shot - it is like snapshot testing but for dynamic data (explanation)

Small print

Author: Gleb Bahmutov <[email protected]> © 2017

• @bahmutov
• glebbahmutov.com
• blog

License: MIT - do anything with the code, but don't blame me if it does not work.

Support: if you find any problems with this module, email / tweet / open issue on Github

MIT License

Copyright (c) 2017 Gleb Bahmutov <[email protected]>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.