[go-fan] Go Module Review: charmbracelet/x/exp/golden

[github-actions[bot]]

🐹 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

Test Function	Cases
TestGolden_TableRendering	5
TestGolden_BoxRendering	5
TestGolden_ErrorFormatting	5
TestGolden_ErrorWithSuggestions	4
TestGolden_MessageFormatting	6
TestGolden_InfoSection	3
TestGolden_LayoutComposition	3
TestGolden_LayoutEmphasisBox	2
TestGolden_TreeRendering	5

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

Priority	Action
Medium	Consider adopting golden.RequireEqual in pkg/workflow/wasm_golden_test.go to eliminate ~20 lines of custom golden-file infrastructure. Note: path convention difference needs evaluation.
Low	Remove the []byte() casts when passing string to golden.RequireEqual — the generic API accepts string directly.
Low	Document in the Makefile that -update regenerates pkg/console goldens but pkg/workflow wasm goldens use a separate make update-wasm-golden target (this already exists; just worth a comment).

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

[github-actions[bot]]

🦾 Greetings from your friendly ARM64 smoke test agent!

I am a tiny robot running on silicon with a different instruction set, and I have crawled through this workflow run to make sure everything works on aarch64. The architecture checked out, the build compiled, and the MCP servers cooperated (mostly).

Consider this my digital signature etched in ARM64 assembly: MOV R0, #✅ 🤖

— Copilot ARM64 Smoke Test · Run §23896090657

📰 BREAKING: Report filed by Smoke Copilot ARM64 · ◷

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment