Save / load named snapshots, useful for tests
npm install snap-shot-core
> Save / load named snapshots, useful for tests
[![NPM][npm-icon] ][npm-url]
[![Build status][ci-image] ][ci-url]
[![semantic-release][semantic-image] ][semantic-url]
[![js-standard-style][standard-image]][standard-url]
[![renovate-app badge][renovate-badge]][renovate-app]
This is the snapshot loading and saving utility, used by
[snap-shot-it][snap-shot-it] and [schema-shot][schema-shot] projects.
Can be used to save snapshots from any testing project.
``sh`
npm install --save-dev snap-shot-core
`js`
const snapShot = require('snap-shot-core')
const what // my object
const out = snapShot.core({
what,
file: __filename, // aliases: file, __filename
specName: 'my test', // or whatever name you want to give,
store, // optional function to preprocess the value before storing
compare: compareFn, // optional function that compares values
raiser: raiseErrorFn, // optional
ext: '.test', // default value is '.snapshot.js'
opts: {
// see below
}
})
The returned value contains both the saved value and the snapshot name
`js`
let out = snapShot.core({
what: 42,
exactSpecName: 'my snapshot'
})
console.log(out)
// {value: 42, key 'my snapshot'}
out = snapShot.core({
what: 42,
specName: 'my snapshot'
})
console.log(out)
// auto-increments counter if we are using
// just the spec name
// {value: 42, key 'my snapshot 1'}
When throwing an error on different value, the error instance will still have key property with the final snapshot name.
All snapshots are saved in a single folder __snapshots__, even if original spec files are nested. See test-nested-specs example folder.
Sometimes you want to store not the value itself, but something derived,
like the object's schema (check out [schema-shot][schema-shot]). You can
pass a function store that transforms the object before saving.compare
For example if we are only interested in the type of value, we can do the
following (paired with the right function).
`js`
const store = x => typeof x
// expected - previously saved "type of" value
// value - current original value
const compare = (
{ expected, value } // return Result
) =>
snapShot({
what,
store,
compare,
})
Note: by default multi line text is saves using ES6 template string, while
everything else is saved using normal serialization using
jsesc.
A function to compare expected and actual value should return Result
instance, preferably [Folktable.Result][result]. A simple one could be
`js${e} !== ${v}
const Result = require('folktale/result')
function compare({ expected, value }) {
const e = JSON.stringify(expected)
const v = JSON.stringify(value)
if (e === v) {
return Result.Ok()
}
return Result.Error()`
}
Another one, that compares values by type could be even simpler
`js
const sameTypes = (a, b) => typeof a === typeof b
const compareTypes = ({ expected, value }) =>
sameTypes(expected, value) ? Result.Ok() : Result.Error('types are different')
`
Note input is an object {expected, value} and if there is a differenceResult.Error(
you should describe it as a string .Result
Why does it return a ? Because it makes [life easier][result post].
[result]: http://folktale.origamitower.com/api/v2.0.0/en/folktale.result.html
[result post]: https://glebbahmutov.com/blog/use-a-little-bit-of-fp/#result-either-for-utility-functions
Default function will compare current and loaded values using compare
function and if the values are different will throw an error. You can provide
your own function to fail a test differently. Your function will be called
with these parameters
`js`
raiser({
value, // current value
expected, // loaded value
specName, // the name of the test
compare, // compare function
})
Default raiser function just throws an Error with good message.
The snapShotCore function returns the _expected_ value.store(what)
If this is the first time, it will be value.expected
Otherwise it will be the loaded value.
You can pass several options to control the behavior. I usually grab them
from the environment variables.
- show - log snapshot value when saving new onedryRun
- - only show the new snapshot value, but do not save itupdate
- - override snapshot value with the new one if there is differenceci
- - the tests are running on CI, which should disallow _saving snapshots_sortSnapshots
- - enable sorting snapshots by name when saving (default is false)useRelativePath
- - use relative paths inside __snapshots__ folder to recreate folder structure to mimic spec file relative path. Default is false.
`js`
// for example to use environment variables
const opts = {
show: Boolean(process.env.SHOW),
dryRun: Boolean(process.env.DRY),
update: Boolean(process.env.UPDATE),
ci: Boolean(process.env.CI),
sortSnapshots: false,
useRelativePath: false
}
snapShot.core({
what,
file: __filename,
specName: 'my test',
compare: compareFn,
ext: '.test',
opts,
})
If opts.ci is not set, it will use is-ci
to determine if running on CI or not.
When you pass useRelativePath: true option, the folder structure inside the __snapshots__ folder will recreate the folder paths to the spec. For example if the specs are in subfolders:
`text`
specs/
foo/
spec.js
bar/
spec.js
Then output snapshots will be saved as
`text`
__snapshots__/
specs/
foo/
spec.js.snapshot.js
bar/
spec.js.snapshot.js
When test names change or tests are updated, new snapshots are saved, but old ones remain
in the snapshot file. To prune the old snapshots, the test runner can pass all current spec
names to prune all other ones. Just call .prune() method and pass the following options
`
* tests: list of current tests. Each object should have
file: the full test filename
specName: the full title of the test
* ext: optional snapshot filename extension
For example see src/prune-spec.js
note this can still leave old snapshot files, if the spec has no tests running or
has been renamed.
note 2 if you run tests with .only it will remove all other snapshots in that file.
This is normal, you will recreated all snapshots once you run all the tests again.
Sometimes you do not want to auto increment the snapshots, or use default test name.
In this case you can pass exactSpecName to just save the snapshot with that key.
`js`
snapShot.core({
what: 42,
exactSpecName: 'computed value',
file: __filename,
})
The snapshot file will have
`js`
exports['computed value'] = 42
When saving strings, the snapshot will be surrounded by newlines to avoid
extra lone first line (looking like exports["name"] = ...). So when saving snapshot text
`text`
line 1
line 2
the snapshot file will have
`js
exports['name'] =
line 1
line 2
The newlines will be trimmed automatically when loading the snapshot value.
Run the code with DEBUG=snap-shot-core option to see more log messages. During testing you can see additional output by adding DEBUG=test environment variable (or both DEBUG=snap-shot-core,test).
If you want verbose output, use DEBUG=snap-shot-core*
In case you execute your tests in watch mode and you notice the snapshots are always new-created for the same set of tests, then you need to restore the counters per file.
tape example:
`js
//foo.test.js
const test = require('tape')
const snapShot = require('snap-shot-core')
test.onFinish(snapShot.restore)
test('one test', function(t) {
t.plan(1)
snapShot.core({
what: 1,
file: __filename,
specName: 'one test',
})
})
`
You can restore / reset a counter for a particular test
`js`
const snapShot = require('snap-shot-core')
snapShot.restore({
file: __filename,
specName: 'this test',
})
Because the snapshots are saved as template literals, back ticks and other "niceties" have to be escaped. This module uses jsesc module to do string escaping. Currently only the minimal set of characters is escaped.
You can re-save snapshot file (for example to escape it again, or to resort the snapshots by name) using bin/resave-snapshots.js script. After installing this module, run bin script
`bash`
$(npm bin)/resave-snapshots [--sort] snapshot-filename
To just re-escape the snapshots omit the --sort` flag.
Author: Gleb Bahmutov <gleb.bahmutov@gmail.com> © 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
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.
[npm-icon]: https://nodei.co/npm/snap-shot-core.svg?downloads=true
[npm-url]: https://npmjs.org/package/snap-shot-core
[ci-image]: https://travis-ci.org/bahmutov/snap-shot-core.svg?branch=master
[ci-url]: https://travis-ci.org/bahmutov/snap-shot-core
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release
[standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[standard-url]: http://standardjs.com/
[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg
[renovate-app]: https://renovateapp.com/
[snap-shot-it]: https://github.com/bahmutov/snap-shot-it
[schema-shot]: https://github.com/bahmutov/schema-shot