golden

Documentation

Overview

Package golden provides tools for comparing large mutli-line strings.

Golden files are files in the ./testdata/ subdirectory of the package under test. Golden files can be automatically updated to match new values by running `go test pkgname -update`. To ensure the update is correct compare the diff of the old expected value to the new expected value.

Index

• Variables
• func Assert(t assert.TestingT, actual string, filename string, msgAndArgs ...interface{})
• func AssertBytes(t assert.TestingT, actual []byte, filename string, msgAndArgs ...interface{})
• func Bytes(actual []byte, filename string) cmp.Comparison
• func FlagUpdate() bool
• func Get(t assert.TestingT, filename string) []byte
• func Open(t assert.TestingT, filename string) *os.File
• func Path(filename string) string
• func String(actual string, filename string) cmp.Comparison

Examples

• Assert
• AssertBytes
• String

Variables

var NormalizeCRLFToLF = os.Getenv("GOTESTTOOLS_GOLDEN_NormalizeCRLFToLF") != "false"

NormalizeCRLFToLF enables end-of-line normalization for actual values passed to Assert and String, as well as the values saved to golden files with -update.

Defaults to true. If you use the core.autocrlf=true git setting on windows you will need to set this to false.

The value may be set to false by setting GOTESTTOOLS_GOLDEN_NormalizeCRLFToLF=false in the environment before running tests.

The default value may change in a future major release.

This does not affect the contents of the golden files themselves. And depending on the git settings on your system (or in github action platform default like windows), the golden files may contain CRLF line endings. You can avoid this by setting the .gitattributes file in your repo to use LF line endings for all files, or just the golden files, by adding the following line to your .gitattributes file:

* text=auto eol=lf

Functions

func Assert

func Assert(t assert.TestingT, actual string, filename string, msgAndArgs ...interface{})

Assert compares actual to the expected value in the golden file.

Running `go test pkgname -update` will write the value of actual to the golden file.

This is equivalent to assert.Assert(t, String(actual, filename))

Example

package main

import (
	"testing"

	"gotest.tools/v3/golden"
)

var t = &testing.T{}

func main() {
	golden.Assert(t, "foo", "foo-content.golden")
}

func AssertBytes

func AssertBytes(
	t assert.TestingT,
	actual []byte,
	filename string,
	msgAndArgs ...interface{},
)

AssertBytes compares actual to the expected value in the golden.

Running `go test pkgname -update` will write the value of actual to the golden file.

This is equivalent to assert.Assert(t, Bytes(actual, filename))

Example

package main

import (
	"testing"

	"gotest.tools/v3/golden"
)

var t = &testing.T{}

func main() {
	golden.AssertBytes(t, []byte("foo"), "foo-content.golden")
}

func Bytes

func Bytes(actual []byte, filename string) cmp.Comparison

Bytes compares actual to the contents of filename and returns success if the bytes are equal.

Running `go test pkgname -update` will write the value of actual to the golden file.

func FlagUpdate

func FlagUpdate() bool

FlagUpdate returns true when the -update flag has been set.

func Get

func Get(t assert.TestingT, filename string) []byte

Get returns the contents of the file in ./testdata

func Open

func Open(t assert.TestingT, filename string) *os.File

Open opens the file in ./testdata

func Path

func Path(filename string) string

Path returns the full path to a file in ./testdata

func String

func String(actual string, filename string) cmp.Comparison

String compares actual to the contents of filename and returns success if the strings are equal.

Running `go test pkgname -update` will write the value of actual to the golden file.

Any \r\n substrings in actual are converted to a single \n character before comparing it to the expected string. When updating the golden file the normalized version will be written to the file. This allows Windows to use the same golden files as other operating systems.

Example

package main

import (
	"testing"

	"gotest.tools/v3/assert"
	"gotest.tools/v3/golden"
)

var t = &testing.T{}

func main() {
	assert.Assert(t, golden.String("foo", "foo-content.golden"))
}