README
¶
Golden tests in Go
The aurum[^name-explanation] package implements golden tests for use in Go unit tests. Values expected from a computation are stored in a file termed "golden file" and differences are reported as test errors. Golden files are only written when requested via a command line flag and if a logical change is detected. Version control is used to track and review changes at the file level.
By default a generic JSON codec is used for storing expected values. The
implementation includes special handling of Protocol
Buffers which need to be serialized through the
protojson
package.
String-like data may be stored in plain-text files (TextCodec). When only
protocol buffers are compared the textproto codec improves readability over
JSON (TextProtoCodec).
[^name-explanation]: Aurum is Latin for gold.
Example usage
func init() {
aurum.Init()
}
func Test(t *testing.T) {
g := aurum.Golden{
Dir: "./testdata",
}
g.Assert(t, "example", []string{"expected", "value"})
}
A more complete code example can be found in the example
directory. To update the golden files:
go test -update_golden_files
Alternatives
Documentation
¶
Index ¶
Constants ¶
const DefaultUpdateFlagName = "update_golden_files"
Variables ¶
var ErrValueDifference = errors.New("values are not equal")
Functions ¶
func Init ¶
func Init(opts ...InitOption)
Initialize the package and register a command line flag. Must be called before parsing flags. Example usage in a test file:
func init() {
aurum.Init()
}
If not called the default values are used.
Types ¶
type Cmp ¶
type Cmp struct {
// Options for comparing values, e.g. [cmpopts.EqualEmpty]. If one of the
// compared values is a [proto.Message] then the [protocmp.Transform]
// option is automatically added.
Options cmp.Options
}
Cmp compares values using cmp.Diff.
type Codec ¶
Codec is the interface implemented by types used for marshalling and unmarshalling values.
type Comparer ¶
Comparer is an interface implemented by types used for checking whether two values are equal or equivalent (the distinction is up to the implementation).
type Golden ¶
type Golden struct {
// Directory for storing golden files. Only used if [FS] is not set.
Dir string
// Filesystem for accessing golden files. Updates are only possible if the
// file system implements [WriteFileFS].
//
// Defaults to [os.DirFS] for [Dir].
FS fs.FS
// Codec for marshalling and unmarshalling values.
//
// Defaults to [JSONCodec].
Codec Codec
// Defaults to [Cmp].
Comparer Comparer
// Options for the default [Cmp] comparer.
CmpOptions cmp.Options
// contains filtered or unexported fields
}
func (*Golden) Assert ¶
Assert checks whether the value matches the stored golden value read from a file.
If enabled via a flag (see Init) golden files are updated if they're missing or differences in values are detected. The name is URL-escaped before being used as a filename and should be of a reasonable length (the exact limits depend on the underlying filesystem).
type InitOption ¶
type InitOption interface {
// contains filtered or unexported methods
}
Interface implemented by initialization options.
type JSONCodec ¶
type JSONCodec struct {
ProtoMarshalOptions protojson.MarshalOptions
ProtoUnmarshalOptions protojson.UnmarshalOptions
}
JSONCodec stores values using the JSON format.
Protocol buffer messages are detected and marshalled using protojson before re-formatting the resulting JSON data. Protojson produces unstable output by design.
type TB ¶
TB is the subset of testing.TB used for golden tests.
type TextCodec ¶
type TextCodec struct {
// Codec to use for unsupported types.
Fallback Codec
}
TextCodec stores values in plain-text files. Supports strings, byte slices, rune slices and values implementing encoding.TextUnmarshaler.
type TextProtoCodec ¶
type TextProtoCodec struct {
ProtoMarshalOptions prototext.MarshalOptions
ProtoUnmarshalOptions prototext.UnmarshalOptions
}
TextProtoCodec stores values using the textproto format. Only protocol buffer messages are supported.
[txtpbfmt] is used to format the resulting data as prototext produces unstable output by design.
Source Files
Directories