Awesome
snap-shot
Jest-like snapshot feature for the rest of us + data-driven testing!
deprecated please use snap-shot-it - it grabs test instance at runtime, avoiding looking at the source code and getting lost in the transpiled code.
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.
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"
*/
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
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}`)
}
})
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 <gleb.bahmutov@gmail.com> © 2017
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 <gleb.bahmutov@gmail.com>
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.