Testing

Bubble Tea uses standard go test plus golden files for renderer output verification.

Test layout

File	Coverage
tea_test.go	Black-box tests of Program.Run lifecycle, message ordering, batch/sequence execution, panic recovery
screen_test.go	Renderer behaviour: alt screen, mouse, cursor, focus reporting, progress bar, window title — golden file comparisons
commands_test.go	Tick, Every, Batch, Sequence
options_test.go	ProgramOptions and their interactions
exec_test.go	tea.Exec releasing/restoring the terminal
logging_test.go	LogToFile

Golden files

The renderer tests (mainly screen_test.go and tea_test.go) use github.com/charmbracelet/x/exp/golden to compare ANSI output against fixtures stored in testdata/. Two top-level subdirectories exist: TestClearMsg and TestViewModel.

If you change rendering output intentionally, regenerate the goldens by passing -update to the affected tests. The helper expects to be run on a Linux host because escape sequences for clipboard/cursor differ on Windows.

Running on Windows

There is one TODO around Windows test coverage at exec_test.go:67 (// TODO: add more tests for windows). PRs that improve Windows coverage are welcome — tty_windows.go and signals_windows.go carry the platform-specific glue.

Race detector

CI runs tests with -race. Many subsystems spawn goroutines (signal handler, resize handler, command runner, render ticker, input reader), so race detector hits are real bugs — please reproduce locally with go test -race ./... before opening a PR that touches tea.go or cursed_renderer.go.

Coverage

go test -race -covermode=atomic -coverprofile=coverage.txt ./... matches CI. Coverage is uploaded to Codecov from the coverage workflow. There is no local coverage threshold gate.

Test environment caveats

• Tests that exercise the renderer set tea.WithOutput to a bytes.Buffer and feed input via tea.WithInput. Real TTY tests would require a pseudo-terminal harness which the project does not currently use.
• tea.WithoutSignals() is used heavily in tests to avoid leaking signal handlers between cases.
• The tests assume TERM=xterm-256color-like behaviour; setting unusual TERM values can change golden output.

Adding a test

1. Place black-box tests in tea_test.go or a new *_test.go next to the file under test.
2. Use tea.NewProgram(model, tea.WithOutput(&buf), tea.WithInput(&buf), tea.WithoutSignals(), tea.WithoutCatchPanics()) for deterministic runs.
3. For renderer-affecting changes, write a screen_test.go-style golden test.
4. Use t.Helper() and t.Cleanup consistently — the existing tests do.