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 Equal(vx, vy interface{}) bool
- func Snapshot(i ...interface{}) error
- func SnapshotJSON(i ...interface{}) error
- func SnapshotJSONT(t TestingT, i ...interface{})
- func SnapshotMulti(snapshotID string, i ...interface{}) error
- func SnapshotT(t TestingT, i ...interface{})
- func Unmarshal(b []byte) (interface{}, error)
- type Config
- func (c *Config) Snapshot(i ...interface{}) error
- func (c *Config) SnapshotJSONT(t TestingT, i ...interface{})
- func (c *Config) SnapshotMulti(snapshotID string, i ...interface{}) error
- func (c *Config) SnapshotT(t TestingT, i ...interface{})
- func (c *Config) WithOptions(configurators ...Configurator) *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 Equal ¶
func Equal(vx, vy interface{}) bool
Equal checks equality between 2 nested interfaces, regardless of sorting order.
func Snapshot ¶
func Snapshot(i ...interface{}) error
Snapshot calls Snapshotter.Snapshot with the global config.
func SnapshotJSON ¶
func SnapshotJSON(i ...interface{}) error
SnapshotJSON calls Snapshotter.SnapshotJSON with the global config.
func SnapshotJSONT ¶
func SnapshotJSONT(t TestingT, i ...interface{})
SnapshotJSONT calls Snapshotter.SnapshotJSONT 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 variable to its previous value stored on the filesystem. An error containing a diff is returned if the snapshots do not match, or if a new snapshot was created.
Snapshot determines the snapshot file automatically from the name of the calling function. As a result it can be called at most once per function. If you want to call Snapshot multiple times in a function, if possible, instead collect the values and call Snapshot with all values at once. Otherwise see SnapshotMulti.
If using snapshots in tests, prefer the SnapshotT function which fails the test directly, rather than requiring your to remember to check the error.
func (*Config) SnapshotJSONT ¶
SnapshotJSONT is the same as SnapshotT but with better JSON comparison support
func (*Config) SnapshotMulti ¶
SnapshotMulti is similar to Snapshot but can be called multiple times from the same function. This is possible by providing a unique id for each snapshot which is appended to the function name to form the snapshot name.
func (*Config) SnapshotT ¶
SnapshotT compares the given variable to the its previous value stored on the filesystem. The current test is failed (with error containing a diff) if the values do not match, or if a new snapshot was created.
SnapshotT determines the snapshot file automatically from the name of the test (using the t.Name() function). As a result, SnapshotT can be called at most once per test. If you want to call SnapshotT multiple times in a test, if possible, instead collect the values and call SnapshotT with all values at once. Alternatively, use sub-tests and call SnapshotT once in each.
If using snapshots in tests, SnapshotT is preferred over Snapshot and SnapshotMulti.
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 ¶
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