golden

README

🔶 Golden

Excruciatingly simple golden file handling.

go get -u github.com/tslamic/golden

How to use it?

func TestJSON(t *testing.T) {
	greet := &greeter{Greeting: "Hello, World!"}

	gf := golden.File("testdata/hello.json", JSON, IgnoreWhitespace)
	gf.Equals(t, greet)
}

It's easy to provide custom attributes:

gf := File("testdata/golden.file", func(d *Data) {
	// apply custom attributes to d here.
})

You can add a custom Marshaller, Differ, and as many Transformer funcs as you'd like. To update the golden files, use the -update flag, or roll your own update mechanism.

License

The MIT License (MIT), Copyright (c) 2019 tslamic

Documentation

Index

• Variables
• type Data
  • func File(path string, opts ...Option) *Data
  • func (d *Data) Add(t Transformer) *Data
  • func (d *Data) Eq(v interface{}) (string, error)
  • func (d *Data) Equals(t *testing.T, v interface{})
  • func (d *Data) Open() (*os.File, error)
• type Differ
• type Marshaller
• type Option
• type Transformer

Variables

var (
	ErrNoPath       = errors.New("no golden file path")
	ErrNoMarshaller = errors.New("no marshaller")
	ErrNoDiffer     = errors.New("no differ")
	ErrNotEqual     = errors.New("not equal")
)

Possible errors when invoking the Eq func.

var ErrUnsupportedType = errors.New("only []byte and string are supported by default, use a custom Marshaller, e.g. JSON")

ErrUnsupportedType is returned when encoding values other than string or a []byte using the DefaultMarshaller.

Types

type Data

type Data struct {
	Path       string
	Perm       os.FileMode
	Marsh      Marshaller
	Diff       Differ
	Transforms []Transformer
	Update     bool
}

Data represents the golden file attributes.

func File

func File(path string, opts ...Option) *Data

File creates a new golden file.

func (*Data) Add

func (d *Data) Add(t Transformer) *Data

func (*Data) Eq

func (d *Data) Eq(v interface{}) (string, error)

Eq compares the value v to the contents of the golden file. If it's not equal, it returns the ErrNotEqual together with a diff string.

func (*Data) Equals

func (d *Data) Equals(t *testing.T, v interface{})

Equals compares the value v to the contents of the golden file.

func (*Data) Open

func (d *Data) Open() (*os.File, error)

Open opens a golden file. Closing of the file is the callers responsibility.

type Differ

type Differ func(t, u []byte) string

Differ returns a diff string between t and u.

var DefaultDiffer Differ = func(t, u []byte) string {
	p := diffmatchpatch.New()
	d := p.DiffMain(string(t), string(u), false)
	return p.DiffPrettyText(d)
}

DefaultDiffer returns a colored diff string between t and u.

type Marshaller

type Marshaller func(v interface{}) ([]byte, error)

Marshaller returns v encoded as []byte.

var DefaultMarshaller Marshaller = func(v interface{}) ([]byte, error) {
	if v == nil {
		return nil, ErrUnsupportedType
	}
	switch v := v.(type) {
	case string:
		return []byte(v), nil
	case []byte:
		return v, nil
	default:
		return nil, ErrUnsupportedType
	}
}

DefaultMarshaller can handle []byte or string type.

type Option

type Option func(*Data)

Option can modify the golden file attributes.

var (
	JSON Option = func(d *Data) {
		d.Marsh = json.Marshal
	}
	XML Option = func(d *Data) {
		d.Marsh = xml.Marshal
	}
	IgnoreWhitespace Option = func(d *Data) {
		d.Add(StripWhitespace)
	}
)

Convenience Options.

type Transformer

type Transformer func(t, u []byte) ([]byte, []byte)

Transformer transforms and returns t and u, respectively.

var StripWhitespace Transformer = func(t, u []byte) ([]byte, []byte) {
	var wg sync.WaitGroup
	wg.Add(2)
	go func() { defer wg.Done(); t = strip(t) }()
	go func() { defer wg.Done(); u = strip(u) }()
	wg.Wait()
	return t, u
}

StripWhitespace removes all whitespace characters.