snapshot

README

Snapshot

Snapshot is a simple library for snapshot testing in Go. I find it useful for testing complex command-line applications when I'm interested in finding regressions to the UI. When you run a test for the first time, the output is written to a snapshot file. Subsequent tests ensure that test output matches your snapshot.

package example

import (
	"testing"

	"github.com/BTBurke/snapshot"
)

func TestOutput(t *testing.T) {

	// This output matches the testoutput.snap in the __snapshots__ directory
	output := []byte("This is my UI output\nAnd it can be complex")
	snapshot.Assert(t, output)

	// If I assert something different, I'll get a test failure and a diff of what changed
	output = []byte("This is my UI output\nAnd it can be *very* complex")
	snapshot.Assert(t, output)

	// Output:
	// Snapshot test failed for: TestOutput.  Diff:
	//
	// --- Expected
	// +++ Received
	// @@ -1,2 +1,2 @@
	// This is my UI output
	// -And it can be complex
	// +And it can be *very* complex
}

Updating snapshots

When you make UI changes and want to create new snapshots, set the environment variable UPDATE_SNAPSHOTS before running your tests.

UPDATE_SNAPSHOTS=true go test -v -cover

Setting a custom snapshot directory and context

By default, snapshots are saved in the __snapshots__ directory relative to the working directory where you run go test. To change this behavior, you can create your own configuration prior to running your snapshot assertions. The snapshot directory should be the full path. You can also change the number of lines of context that are shown around your diffs.

import (
	"testing"

	"github.com/BTBurke/snapshot"
)

func TestOutput(t *testing.T) {

    mycfg, _ := snapshot.New(SnapDirectory("/snaps"), ContextLines(0))

	// This output matches the testoutput.snap in the /snaps directory
	output := []byte("This is my UI output\nAnd it can be complex")
	mycfg.Assert(t, output)

	// If I assert something different, I'll get a test failure and a diff of what changed
	output = []byte("This is my UI output\nAnd it can be *very* complex")
	mycfg.Assert(t, output)

	// Output:
	// Snapshot test failed for: TestOutput.  Diff:
	//
	// --- Expected
	// +++ Received
	// @@ -1,2 +1,2 @@
	// -And it can be complex
	// +And it can be *very* complex
}

Documentation

Index

• func Assert(t testing.TB, b interface{})
• type Config
  • func New(options ...ConfigOption) (*Config, error)
  • func (c *Config) Assert(t testing.TB, b []byte)
• type ConfigOption
  • func ContextLines(n int) ConfigOption
  • func Diffable(b bool) ConfigOption
  • func IgnoreRegex(r string) ConfigOption
  • func SnapDirectory(dir string) ConfigOption
  • func SnapExtension(ext string) ConfigOption

Functions

func Assert

func Assert(t testing.TB, b interface{})

Assert compares the output in b to the snapshot saved for the current test. If the snapshot file does not yet exist for this test, it will be created and the test will pass. If the snapshot file exists and the test output does not match, the test will fail and a diff will be shown. To update your snapshots, set `UPDATE_SNAPSHOTS=true` when running your test suite. The default config stores snapshots in `__snapshots__` relative to the test directory.

Types

type Config

type Config struct {
	// Full path to snapshot directory
	Directory string
	// Number of lines of context to show with snapshot diffs
	Context int
	// Whether output is diffable (false for binary file formats)
	Diffable bool
	// Extension of the snap recording test file.  Can be useful if test file is a binary format and you want to inspect it manually (e.g., images).  Defaults to .snap.
	Extension string
	// contains filtered or unexported fields
}

Config holds values for the full path to the snapshot directory and the number of context lines to show with snapshot diffs.

func New

func New(options ...ConfigOption) (*Config, error)

New creates a new config. Options can set the snapshot directory and context. The snapshot directory defaults to __snapshots__ relative to the current working directory. Default 10 context lines. Use `snapshot.Assert` directly if you don't need to change these defaults.

func (*Config) Assert

func (c *Config) Assert(t testing.TB, b []byte)

Assert compares the output in b to the snapshot saved for the current test. If the snapshot file does not yet exist for this test, it will be created and the test will pass. If the snapshot file exists and the test output does not match, the test will fail and a diff will be shown. To update your snapshots, set `UPDATE_SNAPSHOTS=true` when running your test suite.

See `New` for custom configuration options such as where to save testing snapshots.

type ConfigOption

type ConfigOption func(c *Config) error

ConfigOption is a functional option that sets config values

func ContextLines

func ContextLines(n int) ConfigOption

ContextLines sets the max number of context lines shown before the diff

func Diffable

func Diffable(b bool) ConfigOption

Diffable indicates whether a meaningful diff can be shown for the test case. Defaults to true but can be set to false for binary file formats (e.g., images, PDF files, etc.)

func IgnoreRegex

func IgnoreRegex(r string) ConfigOption

IgnoreRegex sets a regex on the diff output which will ignore stateful changes in the output that should not be considered test failures. For example, PDF files embed creation dates that will change from test to test but can be ignored with an appropriate regex.

func SnapDirectory

func SnapDirectory(dir string) ConfigOption

SnapDirectory sets the snapshot directory to the full path given

func SnapExtension

func SnapExtension(ext string) ConfigOption

SnapExtension changes the extension of the snap test files to `ext` instead of the default .snap