snappy-snaps

Snappy Snaps is a tiny snapshot testing tool which can be used with any test framework and is able to serialize almost anything.

import snap from 'snappy-snaps'

const data = fetchDogs()
const expected = await snap('Dogs', data) 

deepEqual(data, expected)

Installation

This is a Node.js module available through the npm registry. Node.js 18 or higher is required.

$ npm install --save-dev snappy-snaps

Please note this package is ESM only.

Usage

The purpose of snapshot testing is to ensure that the output of a piece of code remains the same over time. The first time your test code is run the data passed to the snap() function will be stored in a file on disk. On subsequent test runs the data will be retrieved from the file, enabling you to test if your code output is the same as the previously stored value.

import { test } from 'node:test'
import assert from 'node:assert'
import snap from 'snappy-snaps'
 
const fetchDog = (id) => fetch(`/api/dogs/${id}`).then((res) => res.json())
 
test('Fetch dog data', async () => {
  const dog = await fetchDog('Rover')
  const expected = await snap('Rover', dog)

  assert.deepEqual(dog, expected)
})

Snappy snaps uses serialize-javascript to serialize and store values rather than JSON.stringify() so it supports a wider range of data types including dates, maps, sets, functions, and regular expressions.

This package does not include any tooling for writing assertions or comparing your data, for this you could use Node's own assert module, a package such as fast-deep-equal or an assertion library like Chai.

The created snapshots should be committed with your other code changes, and reviewed as part of your code review process. If you'd like to learn more, Browserstack maintain a detailed guide to snapshot testing.

Updating snapshots

You can update your snapshots by running your test command with a --updateSnapshot or -u flag, by deleting the snapshot file, specifying the UPDATE_SNAPSHOT environment variable, or setting the update option to true.

Expiring snapshots

To be reminded to update your snapshots periodically you can set a future expiry date using the expires option and providing a timestamp. Running a test after the expiry date will output a warning.

const ONE_YEAR = 1000 * 60 * 60 * 24 * 365
snap('name', data, { expires: Date.now() + ONE_YEAR })

API

snap(key, value, [options] = {})

Returns A promise that is fulfilled with the new or previously stored value.

key

A unique name to identify the snapshot.

value

A serializable value to be stored.

options

Configuration options for the snapshot.

Credits

This plugin was based on the data-snapshot package and snapshot implementation from the Vitest test framework.

License

This package is MIT licensed.