🐹 Go Fan Report: charmbracelet/x/exp/golden

Selected today as the most recently updated unreviewed direct dependency (charmbracelet/x repo pushed 2026-03-16, ranked #1 of 12 unreviewed GitHub-hosted direct deps).

Module Overview

github.com/charmbracelet/x/exp/golden is a tiny but focused golden file testing utility from Charmbracelet's experimental monorepo (charmbracelet/x). It provides a single public function — RequireEqual — that compares test output against stored reference ("golden") files, with special handling for terminal escape sequences and control codes that appear frequently in TUI application output.

The package was purpose-built so Charmbracelet's own TUI libraries (bubbletea, lipgloss, huh, etc.) could have stable, readable golden file tests even when their output contains ANSI escape sequences.

Current Usage in gh-aw

Test groups covered

pkg/console/golden_test.go uses the module across 6 test functions with 28 individual cases total:

• TestGolden_TableRendering — 5 cases (simple, titled, totals, wide, empty)
• TestGolden_BoxRendering — 5 cases (various widths, emoji)
• TestGolden_ErrorFormatting — 5 cases (basic, warning, context, multiline, info)
• TestGolden_ErrorWithSuggestions — 4 cases
• TestGolden_MessageFormatting — 6 cases (success, info, warning, error, command, progress)
• TestGolden_InfoSection — 3 cases (single line, multiline, special chars)

The usage is clean and idiomatic: call the rendering function, pass output to golden.RequireEqual, done. The 44 golden files live under testdata/(TestFuncName)/(case).golden, exactly as the library prescribes.

Research Findings

What the module does (in detail)

// RequireEqual is the sole public API (post-deprecation)
func RequireEqual[T []byte | string](tb testing.TB, out T)

The implementation:

1. Derives the golden file path as testdata/(tb.Name()).golden
2. If -update flag is set, writes the output to the golden file
3. Reads the stored golden file
4. Calls escapeSeqs() on both expected and actual — this calls strconv.Quote line-by-line, converting \x1b[32m → \\x1b[32m etc., while preserving newlines
5. Diffs using github.com/aymanbagabas/go-udiff unified diff format
6. Fails with a three-section message: expected, got, diff

The generic constraint [T []byte | string] means it works with either type without conversion.

Recent activity (charmbracelet/x monorepo)

The last 10 commits to the monorepo are all dependabot dependency bumps (golang.org/x/image, mattn/go-runewidth, charmbracelet/colorprofile) plus one feature commit migrating teatest v2 to use charm.land module paths. The exp/golden subpackage itself has had no recent changes — it is stable and mature for its purpose.

Deprecated API

RequireEqualEscape(tb, out, escapes bool) is marked Deprecated — use RequireEqual instead. The project already uses the correct API. ✓

Improvement Opportunities

🏃 Quick Wins

None required. The pkg/console usage is exactly idiomatic — correct API, correct file layout, clean patterns.

✨ Feature Opportunities

The module is intentionally minimal. The only noteworthy potential: the generic RequireEqual accepts string directly, so any test currently doing golden.RequireEqual(t, []byte(str)) could simplify to golden.RequireEqual(t, str). The project uses []byte(output) conversions throughout — switching to pass the string directly would be a minor style improvement (no functional change).

📐 Best Practice Alignment — Key Finding

pkg/workflow/wasm_golden_test.go implements a parallel custom golden pattern instead of using this library:

// Custom implementation in pkg/workflow/wasm_golden_test.go
var updateGolden = flag.Bool("update", false, "update golden test files")

func isUpdateMode() bool { return *updateGolden }

// Inside test:
if isUpdateMode() {
    os.MkdirAll(dir, 0o755)
    os.WriteFile(goldenPath, []byte(yamlOutput), 0o644)
    return
}
expected, _ := os.ReadFile(goldenPath)
require.Equal(t, string(expected), yamlOutput) // plain string comparison, no diff

vs. the library-based approach in pkg/console/golden_test.go:

golden.RequireEqual(t, []byte(output)) // one line, handles update, diff, escape seqs

What the custom code lacks vs. the library:

• No unified diff output (just raw require.Equal failure)
• No escape sequence normalization (matters less for YAML, but still)
• More boilerplate (~25 lines of custom golden management)
• Different flag variable (updateGolden vs global update)
• Different update trigger UX (-update is the same, but implementation differs)

Migration complexity: Medium. The wasm tests use a custom path (testdata/wasm_golden/TestWasmGolden_CompileFixtures/(name).golden) while the library hardcodes testdata/(tb.Name()).golden. The tb.Name() for a subtest t.Run("foo", ...) becomes TestWasmGolden_CompileFixtures/foo, so the library would store at testdata/TestWasmGolden_CompileFixtures/foo.golden — which matches the existing structure! Migration is viable with a simple directory rename from testdata/wasm_golden/TestWasmGolden_CompileFixtures/ to testdata/TestWasmGolden_CompileFixtures/.

🔧 General Improvements

Consider consolidating golden test patterns. Having two different golden testing mechanisms in the same codebase creates inconsistency for contributors. The charmbracelet/x/exp/golden module is already a direct dependency — using it in both places costs nothing extra.

Recommendations

The module is well-utilized in pkg/console. The only meaningful improvement is unifying the golden testing pattern with pkg/workflow to reduce duplication and improve diff output quality for WASM compiler tests.

Next Steps

1. Consider migrating pkg/workflow/wasm_golden_test.go custom golden logic to use golden.RequireEqual
2. When doing the migration: move testdata/wasm_golden/TestWasmGolden_CompileFixtures/ → testdata/TestWasmGolden_CompileFixtures/
3. Remove the custom updateGolden flag and isUpdateMode() helper (~10 lines)

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

References:

• charmbracelet/x exp/golden source
• go-udiff (diff engine)

AI generated by Go Fan · history

• expires on Mar 20, 2026, 7:25 AM UTC