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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Assert ¶
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 ¶
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 ¶
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 ¶ added in v1.3.0
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 ¶ added in v1.4.0
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 ¶ added in v1.7.0
func SnapExtension(ext string) ConfigOption
SnapExtension changes the extension of the snap test files to `ext` instead of the default .snap
Source Files