bubbletea-testing

Bubble Tea Testing

Write robust, CI-friendly tests for Bubble Tea TUI applications using a three-layer strategy: direct model unit tests, golden file view snapshots, and full-program integration tests via teatest.

Architecture overview

Bubble Tea's Elm Architecture (Init, Update, View) makes TUI apps inherently testable. Update(msg) -> (model, cmd) is a pure function of state and message — no terminal, program, or event loop needed for most tests.

Three-layer strategy:

Layer	Coverage	Speed	Tool
1. Direct model tests	State transitions, commands, view content	~ms	Standard testing
2. Golden file snapshots	Visual regression on View() output	~ms	golden.RequireEqual
3. Full integration	End-to-end user flows	~seconds	teatest.NewTestModel

Target ratio: 80% Layer 1 / 15% Layer 2 / 5% Layer 3.

---

Layer 1: Direct model unit tests

Constructing test messages

Build tea.Msg values directly — they are plain Go structs:

// v1
qKey   := tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("q")}
enter  := tea.KeyMsg{Type: tea.KeyEnter}
ctrlC  := tea.KeyMsg{Type: tea.KeyCtrlC}
down   := tea.KeyMsg{Type: tea.KeyDown}
resize := tea.WindowSizeMsg{Width: 80, Height: 24}

// v2 renames
qKey   := tea.KeyPressMsg{Type: tea.KeyRunes, Runes: []rune("q")}
click  := tea.MouseClickMsg{X: 10, Y: 5, Button: tea.MouseButtonLeft}

Table-driven Update tests

The standard pattern — each case specifies initial state, message, and expected outcome:

func TestUpdate(t *testing.T) {
    tests := []struct {
        name       string
        initial    model
        msg        tea.Msg
        wantCursor int
        wantQuit   bool
    }{
        {
            name:       "down moves cursor",
            initial:    model{cursor: 0, choices: []string{"a", "b", "c"}},
            msg:        tea.KeyMsg{Type: tea.KeyDown},
            wantCursor: 1,
        },
        {
            name:       "cursor stops at bottom",
            initial:    model{cursor: 2, choices: []string{"a", "b", "c"}},
            msg:        tea.KeyMsg{Type: tea.KeyDown},
            wantCursor: 2,
        },
        {
            name:       "q triggers quit",
            initial:    model{},
            msg:        tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune("q")},
            wantQuit:   true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            updated, cmd := tt.initial.Update(tt.msg)
            m := updated.(model)

            if m.cursor != tt.wantCursor {
                t.Errorf("cursor = %d, want %d", m.cursor, tt.wantCursor)
            }
            if tt.wantQuit {
                if cmd == nil {
                    t.Fatal("expected quit command")
                }
                if _, ok := cmd().(tea.QuitMsg); !ok {
                    t.Error("quit command did not return QuitMsg")
                }
            }
        })
    }
}