Documentation ¶
Overview ¶
Package goldsert provides a suite of test helpers which uses golden files to assert marshaling and unmarshaling of given objects.
Each test helper operates in two stages:
Firstly they marshal the provided object to a byte slice and reads the corresponding golden file from disk, follow by verifying both byte slices are identical.
Secondly they unmarshal the content from the golden file, and verifies that the result is identical to the original object.
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.
Index ¶
- func JSONMarshaling(t *testing.T, v interface{})
- func JSONMarshalingP(t *testing.T, v, want interface{})
- func XMLMarshaling(t *testing.T, v interface{})
- func XMLMarshalingP(t *testing.T, v, want interface{})
- func YAMLMarshaling(t *testing.T, v interface{})
- func YAMLMarshalingP(t *testing.T, v, want interface{})
- type Assert
- func (s *Assert) JSONMarshaling(t *testing.T, v interface{})
- func (s *Assert) JSONMarshalingP(t *testing.T, v, want interface{})
- func (s *Assert) XMLMarshaling(t *testing.T, v interface{})
- func (s *Assert) XMLMarshalingP(t *testing.T, v, want interface{})
- func (s *Assert) YAMLMarshaling(t *testing.T, v interface{})
- func (s *Assert) YAMLMarshalingP(t *testing.T, v, want interface{})
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func JSONMarshaling ¶
JSONMarshaling asserts that the given "v" value JSON marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "v" when unmarshaled.
Used for objects that do NOT change when they are marshaled and unmarshaled.
func JSONMarshalingP ¶
JSONMarshalingP asserts that the given "v" value JSON marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "want" when unmarshaled.
Used for objects that change when they are marshaled and unmarshaled.
func XMLMarshaling ¶
XMLMarshaling asserts that the given "v" value XML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "v" when unmarshaled.
Used for objects that do NOT change when they are marshaled and unmarshaled.
func XMLMarshalingP ¶
XMLMarshalingP asserts that the given "v" value XML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "want" when unmarshaled.
Used for objects that change when they are marshaled and unmarshaled.
func YAMLMarshaling ¶
YAMLMarshaling asserts that the given "v" value YAML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "v" when unmarshaled.
Used for objects that do NOT change when they are marshaled and unmarshaled.
func YAMLMarshalingP ¶
YAMLMarshalingP asserts that the given "v" value YAML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "want" when unmarshaled.
Used for objects that change when they are marshaled and unmarshaled.
Types ¶
type Assert ¶
type Assert struct { JSONEncoderFunc func(io.Writer) *json.Encoder JSONDecoderFunc func(io.Reader) *json.Decoder YAMLEncoderFunc func(io.Writer) *yaml.Encoder YAMLDecoderFunc func(io.Reader) *yaml.Decoder XMLEncoderFunc func(io.Writer) *xml.Encoder XMLDecoderFunc func(io.Reader) *xml.Decoder Golden *golden.Golden // NormalizeLineBreaks enables line-break normalization which replaces // Windows' CRLF (\r\n) and Mac Classic CR (\r) line breaks with Unix's LF // (\n) line breaks. NormalizeLineBreaks bool }
Assert is the core of goldsert, holding both configuration and implementation of all assertion methods.
You can customize serialization by setting any of the encoder/decoder function fields to a custom function that returns an encoder/decoder configured as you need.
You can also customize golden file generation by setting the Golden field to a custom *golden.Golden instance. See the github.com/jimeh/go-golden package for details about what can be configured.
func New ¶
func New() *Assert
New returns a new *Assert instance configured with default settings.
The default encoders all specify indentation of two spaces, essentially enforcing pretty formatting for JSON and XML.
The default decoders for JSON and YAML prohibit unknown fields which are not present on the provided struct.
func (*Assert) JSONMarshaling ¶
JSONMarshaling asserts that the given "v" value JSON marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "v" when unmarshaled.
Used for objects that do NOT change when they are marshaled and unmarshaled.
func (*Assert) JSONMarshalingP ¶
JSONMarshalingP asserts that the given "v" value JSON marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "want" when unmarshaled.
Used for objects that change when they are marshaled and unmarshaled.
func (*Assert) XMLMarshaling ¶
XMLMarshaling asserts that the given "v" value XML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "v" when unmarshaled.
Used for objects that do NOT change when they are marshaled and unmarshaled.
func (*Assert) XMLMarshalingP ¶
XMLMarshalingP asserts that the given "v" value XML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "want" when unmarshaled.
Used for objects that change when they are marshaled and unmarshaled.
func (*Assert) YAMLMarshaling ¶
YAMLMarshaling asserts that the given "v" value YAML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "v" when unmarshaled.
Used for objects that do NOT change when they are marshaled and unmarshaled.
func (*Assert) YAMLMarshalingP ¶
YAMLMarshalingP asserts that the given "v" value YAML marshals to an expected value fetched from a golden file on disk, and then verifies that the marshaled result produces a value that is equal to "want" when unmarshaled.
Used for objects that change when they are marshaled and unmarshaled.