jimeh / go-goldsert

A suite of Go test helpers which uses golden files to assert marshaling and unmarshaling of given objects.

go-goldsert

A suite of Go test helpers which uses golden files to assert marshaling and unmarshaling of given objects.

Each test helper operates in two stages:

1. Marshal the provided object to a byte slice and reads the corresponding golden file from disk, follow by verifying both byte slices are identical.
2. Unmarshal the content from the golden file and verify that the result is identical to the original object.

Import

import "github.com/jimeh/go-goldsert"

Usage

Typical usage should look something like this in a tabular test:

type MyStruct struct {
    FooBar string `json:"foo_bar" yaml:"fooBar" xml:"Foo_Bar"`
}

func TestMyStructMarshaling(t *testing.T) {
    tests := []struct {
        name string
        obj  *MyStruct
    }{
        {name: "empty", obj: &MyStruct{}},
        {name: "full", obj: &MyStruct{FooBar: "Hello World!"}},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            goldsert.JSONMarshaling(t, tt.obj)
            goldsert.YAMLMarshaling(t, tt.obj)
            goldsert.XMLMarshaling(t, tt.obj)
        })
    }
}

The above example will read from the following golden files:

• testdata/TestMyStructMarshaling/empty/goldsert_json.golden
• testdata/TestMyStructMarshaling/empty/goldsert_yaml.golden
• testdata/TestMyStructMarshaling/empty/goldsert_xml.golden
• testdata/TestMyStructMarshaling/full/goldsert_json.golden
• testdata/TestMyStructMarshaling/full/goldsert_yaml.golden
• testdata/TestMyStructMarshaling/full/goldsert_xml.golden

If a corresponding golden file cannot be found on disk, the test will fail. To create/update golden files, simply set the GOLDEN_UPDATE environment variable to one of 1, y, t, yes, on, or true when running tests.

It is highly recommended that golden files are committed to source control, as it allow tests to fail when the marshal results for an object changes.

Documentation

Please see the Go Reference for documentation and examples.

License

MIT