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 ¶
- Variables
- func Snapshot(i ...interface{}) error
- func SnapshotMulti(snapshotID string, i ...interface{}) error
- func SnapshotT(t TestingT, i ...interface{})
- type Config
- type Configurator
- func CreateNewAutomatically(createNewAutomatically bool) Configurator
- func EnvVariableName(name string) Configurator
- func FailOnUpdate(failOnUpdate bool) Configurator
- func FatalOnMismatch(fatalOnMismatch bool) Configurator
- func ShouldUpdate(f func() bool) Configurator
- func SnapshotFileExtension(snapshotFileExtension string) Configurator
- func SnapshotSubdirectory(name string) Configurator
- type TestingT
Constants ¶
This section is empty.
Variables ¶
var Global = NewDefaultConfig()
Global is the Config instance used by `cupaloy.SnapshotT` and other package-level functions.
Functions ¶
func Snapshot ¶
func Snapshot(i ...interface{}) error
Snapshot calls Snapshotter.Snapshot with the global config.
func SnapshotMulti ¶
SnapshotMulti calls Snapshotter.SnapshotMulti with the global config.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config provides the same snapshotting functions with additional configuration capabilities.
func New ¶
func New(configurators ...Configurator) *Config
New constructs a new, configured instance of cupaloy using the given Configurators applied to the default config.
func NewDefaultConfig ¶
func NewDefaultConfig() *Config
NewDefaultConfig returns a new Config instance initialised with the same options as the original Global instance (i.e. before any config changes were made to it)
func (*Config) Snapshot ¶
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.
func (*Config) SnapshotMulti ¶
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.
func (*Config) SnapshotT ¶
SnapshotT is identical to Snapshot but gets the snapshot name using t.Name() and calls t.Fail() directly if the snapshots do not match.
func (*Config) WithOptions ¶
func (c *Config) WithOptions(configurators ...Configurator) *Config
WithOptions returns a copy of an existing Config with additional Configurators applied. This can be used to apply a different option for a single call e.g.
snapshotter.WithOptions(cupaloy.SnapshotSubdirectory("testdata")).SnapshotT(t, result)
Or to modify the Global Config e.g.
cupaloy.Global = cupaloy.Global.WithOptions(cupaloy.SnapshotSubdirectory("testdata"))
type Configurator ¶
type Configurator func(*Config)
Configurator is a functional option that can be passed to cupaloy.New() to change snapshotting behaviour.
func CreateNewAutomatically ¶
func CreateNewAutomatically(createNewAutomatically bool) Configurator
CreateNewAutomatically controls whether snapshots should be automatically created if no matching snapshot already exists. Default: true
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. Default: UPDATE_SNAPSHOTS
func FailOnUpdate ¶
func FailOnUpdate(failOnUpdate bool) Configurator
FailOnUpdate controls whether tests should be failed when snapshots are updated. By default this is true to prevent snapshots being accidentally updated in CI. Default: true
func FatalOnMismatch ¶
func FatalOnMismatch(fatalOnMismatch bool) Configurator
FatalOnMismatch controls whether failed tests should fail using t.Fatal which should immediately stop any remaining tests. Will use t.Error on false. Default: false
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. Default: checks for the presence of the UPDATE_SNAPSHOTS environment variable
func SnapshotFileExtension ¶
func SnapshotFileExtension(snapshotFileExtension string) Configurator
SnapshotFileExtension allows you to change the extension of the snapshot files that are written. E.g. if you're snapshotting HTML then adding SnapshotFileExtension(".html") will allow for more easier viewing of snapshots. Default: "", no extension is added.
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 the "testdata" folder Default: .snapshots