README
¶
The goldy is a Go package designed to simplify reading content from golden
files in tests.
Features
- Documentation is part of the golden file.
- Simple file format.
- No dependencies.
Usage
The goldy package provides a single function, goldy.Open, which reads the
content of a golden file.
Opening Golden Files
func Open(t core.T, pth string, opts ...func(*Goldy)) *Goldy
t core.T: A test context (typically a*testing.T).pth string: The golden file path relative to the test file or absolute.
Golden File Format
A golden file must include a --- marker line. Content before this marker is
treated as documentation and ignored, while everything after it is returned as
the test data.
This is multiline documentation about the golden file’s contents. It explains
what the file contains and why it’s used. Documenting golden files helps keep
tests maintainable.
---
Content #1.
Content #2.
It's customary for golden files to have .gld extension.
Example
Below is a practical example showing how to use goldy to read a golden file
and compare it with generated output in a test.
Directory Structure
project/
├── testdata/
│ └── case1.gld
├── my_test.go
Test
Content of my_test.go file.
package project
import (
"testing"
"github.com/ctx42/testing/pkg/goldy"
)
func Test_Generator(t *testing.T) {
t.Run("Generate content", func(t *testing.T) {
// When
have := Generate() // Returns string.
// Then
want := goldy.Open(t, "testdata/case1.gld").String()
if want != have {
format := "expected values to be equal:\n want: %q\n have: %q"
t.Errorf(format, want, have)
}
})
}
Golden file template
For cases where a golden file needs dynamic content, you can use Go text templates.
Golden file template.
---
Content #{{ .first }}.
then use it:
data := WithData(map[string]any{"first": 1})
gld := Open(tspy, "testdata/test_tpl.gld", data)
Error Handling
If goldy encounters issues (e.g., file not found, missing --- marker), it
reports errors via the test context using t.Fatalf, marking the test as
failed. This ensures clear feedback for debugging.
Updating Golden Files
Example:
gld := gold.Open(t, "test.gld")
gld.SetComment("Mock for TestInterface")
gld.SetContent("type TestInterface struct {...}")
gld.Save()
Documentation
¶
Index ¶
Examples ¶
Constants ¶
const Marker = "---\n"
Marker is a separator between a golden file comment and the content.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Goldy ¶ added in v0.7.0
type Goldy struct {
// contains filtered or unexported fields
}
Goldy represents a golden file.
Example golden file:
Multi line golden file documentation. --- Content line #1. Content line #2.
func Open ¶ added in v0.7.0
Open instantiates Goldy based on the provided path to the golden file and options. The golden file content starts after the mandatory Marker line, anything before it is ignored. It's customary to have short golden file documentation before the marker.
Example ¶
package main
import (
"fmt"
"github.com/ctx42/testing/internal/core"
"github.com/ctx42/testing/pkg/goldy"
)
func main() {
tspy := core.NewSpy()
gld := goldy.Open(tspy, "testdata/test_case1.gld")
fmt.Println(gld.String())
}
Output: Content #1. Content #2.
func (*Goldy) Save ¶ added in v0.7.0
func (gld *Goldy) Save()
Save saves the golden file to the original path.
func (*Goldy) SetComment ¶ added in v0.14.0
SetComment sets a comment for the golden file. Implements fluent interface.
func (*Goldy) SetContent ¶ added in v0.11.0
SetContent sets golden file content. If the golden file was a template, it expects a template string. Implements fluent interface.
func (*Goldy) String ¶ added in v0.7.0
String implements fmt.Stringer and returns golden file content.
Source Files