🐹 Greetings from the Go Fan! Today's deep dive is into the golden file testing utility that powers pkg/console test reliability. Let's go!

Module Overview

github.com/charmbracelet/x/exp/golden is a focused, battle-tested golden file testing helper from the Charmbracelet family. It solves a hard problem for TUI projects: comparing test output that contains ANSI escape sequences and terminal control codes reliably across platforms.

The API is intentionally minimal — one primary function:

func RequireEqual[T []byte | string](tb testing.TB, out T)

It handles escape sequence normalization, Windows \r\n normalization, and produces clean unified diffs via go-udiff when output doesn't match the golden file.

Current Usage in gh-aw

• Files: 1 (pkg/console/golden_test.go)
• Import count: 1
• Golden files stored: pkg/console/testdata/<TestName>/<subtest>.golden

38 golden tests covering table rendering, boxes, error formatting, message formatting, info sections, and tree rendering. This is excellent coverage of the pkg/console package's visual output.

Research Findings

Recent Updates

The charmbracelet/x repo has been active (last pushed 2026-03-30), but recent commits are entirely dependency bumps — the exp/golden package itself is stable with no API changes. The latest module version in use (v0.0.0-20251215102626-e0db08df7383) is from December 2025; the repo hasn't released a versioned tag for exp/golden as it's experimental.

Best Practices

• The generic RequireEqual[T []byte | string] accepts both string and []byte — no casting needed for string outputs
• The -update flag (go test -run=TestGolden_... -update) regenerates all golden files in one shot
• The deprecated RequireEqualEscape(tb, out, escapes bool) should be avoided — project is already using the correct API

Improvement Opportunities

🏃 Quick Wins

Unnecessary []byte() casts — the RequireEqual generic accepts string directly, but golden_test.go always converts to []byte:

// Current (unnecessary cast)
golden.RequireEqual(t, []byte(output))
golden.RequireEqual(t, []byte(fullOutput.String()))

// Could be simplified to:
golden.RequireEqual(t, output)
golden.RequireEqual(t, fullOutput.String())

This is a minor style point — both work — but passing strings directly is cleaner and avoids the allocation.

✨ Feature Opportunities

Adopt charmbracelet/x/exp/golden in pkg/workflow/wasm_golden_test.go — this is the most impactful opportunity. The wasm golden test file re-implements the entire golden file workflow manually:

// wasm_golden_test.go manually re-implements:
var updateGolden = flag.Bool("update", false, "update golden test files")

// ... then manually:
if isUpdateMode() {
    require.NoError(t, os.MkdirAll(dir, 0o755))
    require.NoError(t, os.WriteFile(goldenPath, []byte(...), 0o644))
    return
}
expected, err := os.ReadFile(goldenPath)
require.NoError(t, err, "golden file not found for %s (run with -update to create)", fixture)
require.Equal(t, string(expected), ..., "output differs from golden for %s", fixture)

The library already handles all of this. Additionally, the manual approach misses the escape sequence normalization and unified diff output that charmbracelet/x/exp/golden provides for free.

The one complication: wasm golden files use a non-standard path structure (testdata/wasm_golden/TestWasmGolden_CompileFixtures/<name>.golden instead of testdata/<TestName>.golden). The library hardcodes testdata/<tb.Name()>.golden, which would require the test to be restructured slightly to align with this convention — or the library's path could be replicated. This is a judgment call.

📐 Best Practice Alignment

Duplicate -update flag definition — both test files define var update = flag.Bool("update", false, ...) independently. Since they're in different packages, this works without conflict, but it means the behavior isn't unified: running go test ./... -update would regenerate pkg/console golden files but NOT pkg/workflow wasm golden files because they use a differently-named variable (updateGolden vs the library's internal update). Consider documenting this distinction in the Makefile.

TestGolden_LayoutComposition and TestGolden_LayoutEmphasisBox tests — These test functions appear commented out in the test file (replaced with empty stubs) but golden files exist for them in testdata/. This is fine (the golden files are artifacts of past test runs), but worth keeping in sync if those tests are removed permanently.

🔧 General Improvements

The charmbracelet/x/exp/golden library is well-suited for exactly what this project uses it for. The integration in pkg/console is clean, idiomatic, and comprehensive. The main gap is the unused opportunity to consolidate pkg/workflow's custom golden infrastructure with the same library.

Recommendations

Next Steps

• Review whether pkg/workflow/wasm_golden_test.go could restructure its test naming to align with testdata/<tb.Name()>.golden convention, enabling adoption of the library
• Keep an eye on charmbracelet/x/exp/golden for a stable (non-pseudo-version) release

Module summary saved to: scratchpad/mods/charmbracelet-x-exp-golden.md

References:

• §23889221648

AI generated by Go Fan · history

• expires on Apr 3, 2026, 7:34 AM UTC