aureus

README

Aureus

A test runner for executing "golden file" tests in Go.

What is a golden file?

A "golden file" is a file that represents the expected output of some test. When the test is executed, the output of the system under test is compared to the content of the golden file — if they differ, the test fails.

What does Aureus do?

Aureus recursively scans directories for golden file tests expressed either as flat files, or as code blocks within Markdown documents. By default it scans the testdata directory within the current working directory.

Flat files

Files with names matching the <group>.input[.<extension>] and <group>.output[.<extension> patterns are treated as test inputs and outputs, respectively.

For each pair of input and output files with the same <group> prefix, a user-defined function is invoked. The function must produce output that matches the content of the output file, otherwise the test fails.

The run_test.go illustrates how to use Aureus to execute the flat-file tests in the testdata directory.

Markdown documents

As an alternative to (or in combination with) flat-file tests, Aureus can load inputs and outputs from fenced code blocks within Markdown documents.

Code blocks annotated with the au:input or au:output attribute are treated as a test input or output, respectively. The au:group attribute is used to group the inputs and outputs.

This file is itself an example of a Markdown-based test. It confirms the behavior of a basic JSON pretty-printer. Given this unformatted JSON value:

{ "one": 1, "two": 2 }

We expect our formatter function to produce the following output:

{
  "one": 1,
  "two": 2
}

View the README source to see how the code blocks are annotated for use with Aureus, and run_test.go to see how to execute the tests.

Documentation

Overview

Package aureus runs "golden file" style tests defined in Markdown documents.

Index

• func Run[T runner.TestingT[T]](t T, g OutputGenerator[T], options ...RunOption)
• type Input
• type Output
• type OutputGenerator
• type RunOption
  • func AssertionFilter(pred func(test.Assertion) bool) RunOption
  • func Bless(on bool) RunOption
  • func FromDir(dir string) RunOption
  • func Recursive(on bool) RunOption
  • func TrimSpace(on bool) RunOption
• type TestingT

Functions

func Run

func Run[T runner.TestingT[T]](
	t T,
	g OutputGenerator[T],
	options ...RunOption,
)

Run searches a directory for tests and executes them as sub-tests of t.

By default it searches the ./testdata directory; use the FromDir option to search a different directory.

g is an OutputGenerator that produces output from input values for each test. If the output produced by g does not match the test's expected output the test fails.

Types

type Input

type Input interface {
	io.Reader

	// Language returns the language of the input value, if known, e.g. "json",
	// "yaml", etc.
	Language() string

	// Attributes returns a set of key-value pairs that provide additional
	// loader-specific information about the input.
	Attributes() map[string]string
}

Input is an interface for the input to a test.

type Output

type Output interface {
	io.Writer

	// Language returns the expected language of the output value, if known,
	// e.g. "json", "yaml", etc.
	Language() string

	// Attributes returns a set of key-value pairs that provide additional
	// loader-specific information about the expected output.
	Attributes() map[string]string
}

Output is an interface for producing the output for a test.

type OutputGenerator

type OutputGenerator[T TestingT[T]] func(T, Input, Output) error

OutputGenerator produces the output of a specific test.

type RunOption

type RunOption func(*runOptions)

RunOption is an option that changes the behavior of Run.

func AssertionFilter

func AssertionFilter(pred func(test.Assertion) bool) RunOption

AssertionFilter is a RunOption limits test execution to those tests that use a language that matches the given predicate function. It does not prevent the tests from being loaded.

func Bless

func Bless(on bool) RunOption

Bless is a RunOption that enables or disables "blessing" of failed tests.

If blessing is enabled, the file containing the expected output of each failed assertion is replaced with the actual output.

By default blessing is disabled unless the -aureus.bless flag is set on the command line.

func FromDir

func FromDir(dir string) RunOption

FromDir is a RunOption that sets the directory to search for tests. By default the ./testdata directory is used.

func Recursive

func Recursive(on bool) RunOption

Recursive is a RunOption that enables or disables recursion when searching for test cases. By default recursion is enabled.

func TrimSpace

func TrimSpace(on bool) RunOption

TrimSpace is a RunOption that enables or disables trimming of leading and trailing whitespace from test outputs. By default trimming is enabled.

type TestingT

type TestingT[Self any] interface {
	Helper()
	Run(string, func(Self)) bool
	Log(...any)
	SkipNow()
	Fail()
}

TestingT is a constraint for the subset of testing.T that is used by Aureus to execute tests.