README
¶
Incredibly simple Go snapshot testing: cupaloy takes a snapshot of your test output and compares it to a snapshot committed alongside your tests. If the values don't match then you'll be forced to update the snapshot file before the test passes.
Snapshot files are handled automagically: just use the cupaloy.SnapshotT(t, value) function in your tests and cupaloy will automatically find the relevant snapshot file and compare it with the given value.
Usage
func TestExample(t *testing.T) {
result := someFunction()
// check that the result is the same as the last time the snapshot was updated
// if the result has changed then the test will be failed with an error containing
// a diff of the changes
cupaloy.SnapshotT(t, result)
}
To update the snapshots simply set the UPDATE_SNAPSHOTS environment variable and run your tests e.g.
UPDATE_SNAPSHOTS=true go test ./...
This will fail all tests where the snapshot was updated (to stop you accidentally updating snapshots in CI) but your snapshot files will now have been updated to reflect the current output of your code.
Installation
go get -u github.com/bradleyjkemp/cupaloy
Further Examples
Table driven tests
var testCases = map[string][]string{
"TestCaseOne": []string{......},
"AnotherTestCase": []string{......},
....
}
func TestCases(t *testing.T) {
for testName, args := range testCases {
t.Run(testName, func(t *testing.T) {
result := functionUnderTest(args...)
cupaloy.SnapshotT(t, result)
})
}
}
Changing output directory
func TestSubdirectory(t *testing.T) {
result := someFunction()
snapshotter := cupaloy.New(cupaloy.SnapshotSubdirectory("testdata"))
err := snapshotter.Snapshot(result)
if err != nil {
t.Fatalf("error: %s", err)
}
}
For further usage examples see basic_test.go and advanced_test.go in the examples/ directory which are both kept up to date and run on CI.
Documentation
¶
Overview ¶
Package cupaloy provides a simple api for snapshot testing in golang: test that your changes don't unexpectedly alter the results of your code.
cupaloy takes a snapshot of a given value and compares it to a snapshot committed alongside your tests. If the values don't match then you'll be forced to update the snapshot file before the test passes.
Snapshot files are handled automagically: just use the cupaloy.Snapshot(value) function in your tests and cupaloy will automatically find the relevant snapshot file and compare it with the given value.
Installation
go get -u github.com/bradleyjkemp/cupaloy
Usage
func TestExample(t *testing.T) {
result := someFunction()
// check that the result is the same as the last time the snapshot was updated
// if the result has changed then the test will be failed with an error containing
// a diff of the changes
cupaloy.SnapshotT(t, result)
}
To update the snapshots simply set the UPDATE_SNAPSHOTS environment variable and run your tests e.g.
UPDATE_SNAPSHOTS=true go test ./...
Your snapshot files will now have been updated to reflect the current output of your code.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Snapshot ¶
func Snapshot(i ...interface{}) error
Snapshot calls Snapshotter.Snapshot with the default config.
func SnapshotMulti ¶
SnapshotMulti calls Snapshotter.SnapshotMulti with the default config.
Types ¶
type Configurator ¶
type Configurator func(*config)
Configurator is a functional option that can be passed to cupaloy.New() to change snapshotting behaviour.
func EnvVariableName ¶
func EnvVariableName(name string) Configurator
EnvVariableName can be used to customize the environment variable that determines whether snapshots should be updated e.g.
cupaloy.New(EnvVariableName("UPDATE"))
Will create an instance where snapshots will be updated if the UPDATE environment variable is set, instead of the default of UPDATE_SNAPSHOTS.
func ShouldUpdate ¶ added in v1.3.0
func ShouldUpdate(f func() bool) Configurator
ShouldUpdate can be used to provide custom logic to decide whether or not to update a snapshot e.g.
var update = flag.Bool("update", false, "update snapshots")
cupaloy.New(ShouldUpdate(func () bool { return *update })
Will create an instance where snapshots are updated if the --update flag is passed to go test.
func SnapshotSubdirectory ¶
func SnapshotSubdirectory(name string) Configurator
SnapshotSubdirectory can be used to customize the location that snapshots are stored in. e.g.
cupaloy.New(SnapshotSubdirectory("testdata"))
Will create an instance where snapshots are stored in testdata/ rather than the default .snapshots/
type Snapshotter ¶
type Snapshotter interface {
// Snapshot compares the given value to the it's previous value stored on the filesystem.
// An error containing a diff is returned if the snapshots do not match.
// Snapshot determines the snapshot file automatically from the name of the calling function.
Snapshot(i ...interface{}) error
// SnapshotMulti is identical to Snapshot but can be called multiple times from the same function.
// This is done by providing a unique snapshotId for each invocation.
SnapshotMulti(snapshotID string, i ...interface{}) error
// SnapshotT is identical to Snapshot but gets the snapshot name using
// t.Name() and calls t.Fail() directly if the snapshots do not match.
SnapshotT(t *testing.T, i ...interface{})
}
Snapshotter is the API for taking snapshots of values in your tests.
func New ¶
func New(configurators ...Configurator) Snapshotter
New constructs a new, configured instance of cupaloy using the given Configurators.
Source Files
Directories