testutils

Documentation

Overview

Package testutils provides shared utilities for testing.

Index

• func NewSlogStabilizer(tb testing.TB) func([]string, slog.Attr) slog.Attr
• func ReadFile(tb testing.TB, pathElems ...string) []byte
• func Stabilize(tb testing.TB, data []byte) []byte
• func WriteFile(tb testing.TB, data []byte, pathElems ...string)
• type ErrorAssertion
  • func AssertErrorContains(substr string) ErrorAssertion
  • func AssertErrorIs(target error) ErrorAssertion
  • func RequireErrorContains(substr string) ErrorAssertion
  • func RequireErrorIs(target error) ErrorAssertion
• type Golden
  • func NewGolden(tb testing.TB) *Golden
  • func (g *Golden) AssertMatch(got any)
  • func (g *Golden) RequireMatch(got any)

Functions

func NewSlogStabilizer

func NewSlogStabilizer(tb testing.TB) func([]string, slog.Attr) slog.Attr

NewSlogStabilizer returns an attribute replacer function for slog.Logger that replaces non-deterministic and environment-dependent attribute values with stable values.

The function replaces all attribute values of type time.Time and time.Duration with their zero values.

If a string value begins with the system's temporary directory path, or the current user's home directory, the path is replaced with a stable path.

Usage:

logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
    ReplaceAttr: testutils.NewSlogStabilizer(t)
}))

func ReadFile

func ReadFile(tb testing.TB, pathElems ...string) []byte

func Stabilize

func Stabilize(tb testing.TB, data []byte) []byte

Stabilize replaces non-deterministic and environment-dependent values in [data] with stable values.

The function replaces all timestamps in RFC3339 format with the zero value and all Go version strings with "go0.0.0".

func WriteFile

func WriteFile(tb testing.TB, data []byte, pathElems ...string)

Types

type ErrorAssertion

type ErrorAssertion func(testing.TB, error) bool

ErrorAssertion is a function that asserts an error.

The function is passed the test context and the error to assert. If the error does not match the assertion, the test is failed and function returns false.

func AssertErrorContains

func AssertErrorContains(substr string) ErrorAssertion

AssertErrorContains asserts that the given error contains the provided substring.

func AssertErrorIs

func AssertErrorIs(target error) ErrorAssertion

AssertErrorIs asserts that the given error is the target error.

func RequireErrorContains

func RequireErrorContains(substr string) ErrorAssertion

RequireErrorContains is like AssertErrorContains, but fails the test immediately if the assertion fails.

func RequireErrorIs

func RequireErrorIs(target error) ErrorAssertion

RequireErrorIs is like AssertErrorIs, but fails the test immediately if the assertion fails.

type Golden

type Golden struct {
	// contains filtered or unexported fields
}

Golden provides functionality for testing with golden files.

Read more on golden file testing: https://ieftimov.com/posts/testing-in-go-golden-files/

func NewGolden

func NewGolden(tb testing.TB) *Golden

NewGolden returns a new golden file test helper for the given testing.TB.

Golden files are stored in the testdata/golden directory. Each test has a golden file with the same name as the test function. The golden file contains the expected output of the test. When the test is run, the actual output is compared to the golden file. If the actual output does not match the golden file, the actual output is written to a file in the same directory as the golden file for debugging purposes.

func (*Golden) AssertMatch

func (g *Golden) AssertMatch(got any)

AssertMatch asserts that the provided value matches the expected, golden value.

If the value does not match, the test will fail and the actual value will be written to a file in the same directory as the golden file for debugging purposes. If the values differ because of an expected change, the file can be renamed to the golden file, or the UPDATE_GOLDEN environment variable can be set to update the golden file.

NOTE: the golden and actual values are compared by their marshaled JSON form and are also written to files in this format. This makes it easy to read and compare the file contents.

func (*Golden) RequireMatch

func (g *Golden) RequireMatch(got any)

RequireMatch is like [AssertMatch], but will fail the test immediately if the provided value does not match the expected, golden value.