Documentation
¶
Overview ¶
Package golden testing with golden files in Go. A golden file is the expected output of test, stored as a separate file rather than as a string literal inside the test code. So when the test is executed, it will read data from the file and compare it to the output produced by the functionality under test.
When writing unit tests, there comes a point when you need to check that the complex output of a function matches your expectations. This could be binary data (like an Image, JSON, HTML etc). Golden files are a way of ensuring your function output matches its .golden file. It’s a pattern used in the Go standard library.
One of the advantages of the gold files approach is that you can easily update the test data using the command line flag without copying the data into the text variables of go this is very convenient in case of significant changes in the behavior of the system but also requires attention to the changed test data and checking the correctness of the new golden results.
A special cli is provided in the package. The special flag `-update` is provided in the package for conveniently updating ethos files, for example, using the following command:
go test ./... -update
Golden files are placed in directory `testdata` this directory is ignored by the standard tools go, and it can accommodate a variety of data used in test or samples.
Index ¶
- Constants
- func Assert(t tb, got []byte)
- func Read(t tb, tar target) []byte
- func Run(t tb, do func(input []byte) (outcome []byte, err error))
- type Tool
- func (tool Tool) Assert(got []byte)
- func (tool Tool) Read() (bs []byte)
- func (tool Tool) Run(do func(input []byte) (got []byte, err error))
- func (tool Tool) SetIndex(index uint8) Tool
- func (tool Tool) SetPrefix(prefix string) Tool
- func (tool Tool) SetTarget(tar target) Tool
- func (tool Tool) SetTest(t tb) Tool
- func (tool Tool) Update(bs []byte)
Examples ¶
Constants ¶
const ( // Input file target. Input target = iota // Golden file target. Golden )
Variables ¶
This section is empty.
Functions ¶
func Assert ¶
func Assert(t tb, got []byte)
Assert is a tool to compare the actual value obtained in the test and the value from the golden file. Also built-in functionality for updating golden files using the command line flag.
Example ¶
In the current example, the value of `got` will be compared with the value of `want` that we get from the file `testdata/ExampleAssert.golden` and after comparing the data if there is a difference, the test will be aborted with an error. If you run the test flag is used with the `-update` data from the variable `got` is written in the golden file.
The test name is assumed to be equal to ExampleAssert.
package main
import (
"encoding/base64"
"testing"
"github.com/xorcare/golden"
)
// It is necessary for the syntactic correctness of the examples.
var t = &testing.T{}
func main() {
got, err := base64.RawURLEncoding.DecodeString("Z29sZGVu")
if err != nil {
t.Fatalf("%s", err)
}
golden.Assert(t, got)
}
Output:
func Read ¶
func Read(t tb, tar target) []byte
Read is a functional for reading both input and golden files using the appropriate target.
Example ¶
ExampleRead the example shows how you can use the global api to read files together with the already considered golden.Assert.
The test name is assumed to be equal to ExampleRead.
package main
import (
"encoding/base64"
"testing"
"github.com/xorcare/golden"
)
// It is necessary for the syntactic correctness of the examples.
var t = &testing.T{}
func main() {
input := string(golden.Read(t, golden.Input))
got, err := base64.RawURLEncoding.DecodeString(input)
if err != nil {
t.Fatal(err)
}
golden.Assert(t, got)
}
Output:
func Run ¶
Run is a functional that automates the process of reading the input file of the test bytes and the execution of the input function of testing and checking the results.
Example ¶
In the current example, when you run the Run function, the data from the `testdata/ExampleRun.input` file will be read and with this data will be called the function which is passed in, as a result of the function execution we will get the `got` data and possibly an error which will be processed by the internal method implementation. The `got` will be compared with the meaning `want` which we get from the file `test data/ExampleRun.golden` and after data comparison in case of differences, the test will be fail. If you run the test flag is used with the `-update` data from the variable `got` is written in the golden file.
The test name is assumed to be equal to ExampleRun.
package main
import (
"encoding/base64"
"testing"
"github.com/xorcare/golden"
)
// It is necessary for the syntactic correctness of the examples.
var t = &testing.T{}
func main() {
golden.Run(t, func(input []byte) (got []byte, err error) {
return base64.RawURLEncoding.DecodeString(string(input))
})
}
Output:
Types ¶
type Tool ¶
type Tool struct {
// contains filtered or unexported fields
}
Tool implements the basic logic of working with golden files. All functionality is implemented through a non-mutating state machine, which at a certain point in time can perform an action on the basis of the state or change any parameter by creating a new copy of the state.
func SetTest ¶
func SetTest(t tb) Tool
SetTest is a mechanism to create a new copy of the base Tool object for advanced use. This method replaces the constructor for the Tool structure.
func (Tool) Assert ¶
Assert is a tool to compare the actual value obtained in the test and the value from the golden file. Also built-in functionality for updating golden files using the command line flag.
func (Tool) Read ¶
Read is a functional for reading both input and golden files using the appropriate target.
func (Tool) Run ¶
Run is a functional that automates the process of reading the input file of the test bytes and the execution of the input function of testing and checking the results.
func (Tool) SetIndex ¶
SetIndex a index value setter. DEPRECATED: Now you need to use SetPrefix method.