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 []byte)
• 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 SnapDirectory(dir string) ConfigOption

Functions

func Assert

func 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. 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
}

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 SnapDirectory

func SnapDirectory(dir string) ConfigOption

SnapDirectory sets the snapshot directory to the full path given