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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
func Run[T runner.TestingT[T]](t T, g OutputGenerator, options ...RunOption)
Run searches a directory for "golden" tests and executes them as sub-tests of t.
By default is searches the ./testdata directory for test cases. This can be changed using the WithDir option.
g is a function that generates output from input values. It is called for each test case. If the output it produces does not match the expected output.
Types ¶
type ContentMetaData ¶
type ContentMetaData = test.ContentMetaData
ContentMetaData contains information about input or output content.
type OutputGenerator ¶
type OutputGenerator func( w io.Writer, in Content, out ContentMetaData, ) error
OutputGenerator produced output for a test case's input.
in is the input data for the test case. out is meta-data about the expected output, which may be used to influence the kind of output that the generator writes to w.
type RunOption ¶
type RunOption func(*runOptions)
RunOption is an option that changes the behavior of Run.
func WithDir ¶
WithDir is a RunOption that sets the directory to search for test cases. By default the ./testdata directory is used.
func WithRecursion ¶
WithRecursion is a RunOption that enables or disables recursion when searching for test cases. By default recursion is enabled.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
diff
Package diff implements a basic diff algorithm equivalent to patience diff.
|
Package diff implements a basic diff algorithm equivalent to patience diff. |
|
loader
Package loader loads tests from various sources.
|
Package loader loads tests from various sources. |
|
loader/fileloader
Package fileloader loads [test.Test] values from files containing test inputs and expected outputs.
|
Package fileloader loads [test.Test] values from files containing test inputs and expected outputs. |
|
loader/internal/loadertest
Package loadertest provides a basic golden-file style test running for testing Aureus' internal loader implementations.
|
Package loadertest provides a basic golden-file style test running for testing Aureus' internal loader implementations. |
|
loader/markdownloader
Package markdownloader loads [test.Test] values from Markdown files containing code blocks representing test inputs and expected outputs.
|
Package markdownloader loads [test.Test] values from Markdown files containing code blocks representing test inputs and expected outputs. |
|
rootfs
Package rootfs provides an [fs.FS] implementation that uses the OS's root file system.
|
Package rootfs provides an [fs.FS] implementation that uses the OS's root file system. |
|
runner
Package runner executes [test.Test] values under Go's native test framework and other test frameworks with a similar interface.
|
Package runner executes [test.Test] values under Go's native test framework and other test frameworks with a similar interface. |
|
test
Package test defines a tree structure that describes the tests loaded from one or more Aureus Markdown documents.
|
Package test defines a tree structure that describes the tests loaded from one or more Aureus Markdown documents. |