1package cupaloy
2
3// Configurator is a functional option that can be passed to cupaloy.New() to change snapshotting behaviour.
4type Configurator func(*Config)
5
6// EnvVariableName can be used to customize the environment variable that determines whether snapshots
7// should be updated e.g.
8//  cupaloy.New(EnvVariableName("UPDATE"))
9// Will create an instance where snapshots will be updated if the UPDATE environment variable is set.
10// Default: UPDATE_SNAPSHOTS
11func EnvVariableName(name string) Configurator {
12	return func(c *Config) {
13		c.shouldUpdate = func() bool {
14			return envVariableSet(name)
15		}
16	}
17}
18
19// ShouldUpdate can be used to provide custom logic to decide whether or not to update a snapshot
20// e.g.
21//   var update = flag.Bool("update", false, "update snapshots")
22//   cupaloy.New(ShouldUpdate(func () bool { return *update })
23// Will create an instance where snapshots are updated if the --update flag is passed to go test.
24// Default: checks for the presence of the UPDATE_SNAPSHOTS environment variable
25func ShouldUpdate(f func() bool) Configurator {
26	return func(c *Config) {
27		c.shouldUpdate = f
28	}
29}
30
31// SnapshotSubdirectory can be used to customize the location that snapshots are stored in.
32// e.g.
33//  cupaloy.New(SnapshotSubdirectory("testdata"))
34// Will create an instance where snapshots are stored in the "testdata" folder
35// Default: .snapshots
36func SnapshotSubdirectory(name string) Configurator {
37	return func(c *Config) {
38		c.subDirName = name
39	}
40}
41
42// FailOnUpdate controls whether tests should be failed when snapshots are updated.
43// By default this is true to prevent snapshots being accidentally updated in CI.
44// Default: true
45func FailOnUpdate(failOnUpdate bool) Configurator {
46	return func(c *Config) {
47		c.failOnUpdate = failOnUpdate
48	}
49}
50
51// CreateNewAutomatically controls whether snapshots should be automatically created
52// if no matching snapshot already exists.
53// Default: true
54func CreateNewAutomatically(createNewAutomatically bool) Configurator {
55	return func(c *Config) {
56		c.createNewAutomatically = createNewAutomatically
57	}
58}
59
60// FatalOnMismatch controls whether failed tests should fail using t.Fatal which should
61// immediately stop any remaining tests. Will use t.Error on false.
62// Default: false
63func FatalOnMismatch(fatalOnMismatch bool) Configurator {
64	return func(c *Config) {
65		c.fatalOnMismatch = fatalOnMismatch
66	}
67}
68
69// SnapshotFileExtension allows you to change the extension of the snapshot files
70// that are written. E.g. if you're snapshotting HTML then adding SnapshotFileExtension(".html")
71// will allow for more easier viewing of snapshots.
72// Default: "", no extension is added.
73func SnapshotFileExtension(snapshotFileExtension string) Configurator {
74	return func(c *Config) {
75		c.snapshotFileExtension = snapshotFileExtension
76	}
77}
78
79// Config provides the same snapshotting functions with additional configuration capabilities.
80type Config struct {
81	shouldUpdate           func() bool
82	subDirName             string
83	failOnUpdate           bool
84	createNewAutomatically bool
85	fatalOnMismatch        bool
86	snapshotFileExtension  string
87}
88
89// NewDefaultConfig returns a new Config instance initialised with the same options as
90// the original Global instance (i.e. before any config changes were made to it)
91func NewDefaultConfig() *Config {
92	return (&Config{}).WithOptions(
93		SnapshotSubdirectory(".snapshots"),
94		EnvVariableName("UPDATE_SNAPSHOTS"),
95		FailOnUpdate(true),
96		CreateNewAutomatically(true),
97		FatalOnMismatch(false),
98		SnapshotFileExtension(""),
99	)
100}
101
102// Global is the Config instance used by `cupaloy.SnapshotT` and other package-level functions.
103var Global = NewDefaultConfig()
104
105func (c *Config) clone() *Config {
106	return &Config{
107		shouldUpdate:           c.shouldUpdate,
108		subDirName:             c.subDirName,
109		failOnUpdate:           c.failOnUpdate,
110		createNewAutomatically: c.createNewAutomatically,
111		fatalOnMismatch:        c.fatalOnMismatch,
112		snapshotFileExtension:  c.snapshotFileExtension,
113	}
114}
115