golden

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 9, 2019 License: BSD-3-Clause Imports: 7 Imported by: 0

README

Golden

Build Status codecov Go Report Card GoDoc

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.

Examples

Using golden.Assert - to check and save the data in the golden file.

func TestDecode(t *testing.T) {
    got, err := base64.RawURLEncoding.DecodeString("Z29sZGVu")
    if err != nil {
        t.Fatal(err)
    }

    golden.Assert(t, got)
}

Using golden.Run - to automatically read the input file, run the function you created and compare the results with the golden files.

func TestDecode(t *testing.T) {
    golden.Run(t, func(input []byte) (got []byte, err error) {
        return base64.RawURLEncoding.DecodeString(string(input))
    })
}

Using golden.Read - you can use golden code to create your own codebase, such as reading from an input file.

func TestDecode(t *testing.T) {
    input := string(golden.Read(t, golden.Input))
    got, err := base64.RawURLEncoding.DecodeString(input)
    if err != nil {
        t.Fatal(err)
    }
    
    golden.Assert(t, got)
}

Inspiration

License

© Vasiliy Vasilyuk, 2019

Released under the BSD 3-Clause License.

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

Examples

Constants

View Source
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)
}

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)
}

func Run

func Run(t tb, do func(input []byte) (outcome []byte, err error))

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))
	})
}

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

func (tool Tool) Assert(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.

func (Tool) Read

func (tool Tool) Read() (bs []byte)

Read is a functional for reading both input and golden files using the appropriate target.

func (Tool) Run

func (tool Tool) Run(do func(input []byte) (got []byte, err error))

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

func (tool Tool) SetIndex(index uint8) Tool

SetIndex a index value setter.

func (Tool) SetPrefix added in v0.3.0

func (tool Tool) SetPrefix(prefix string) Tool

SetPrefix a prefix value setter.

func (Tool) SetTarget

func (tool Tool) SetTarget(tar target) Tool

SetTarget a target value setter.

func (Tool) SetTest

func (tool Tool) SetTest(t tb) Tool

SetTest a test value setter in the call chain must be used first to prevent abnormal situations when using other methods.

func (Tool) Update

func (tool Tool) Update(bs []byte)

Update functional reviewer is the need to update the golden files and doing it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL