Install
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.
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 <[email protected]> © 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 <[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.
