Skip to content

carapace-sh/carapace-bin / skills/bubbletea

bubbletea

Verified

Use when working with Bubble Tea (charmbracelet/bubbletea) — the Elm Architecture TUI framework for Go. Covers the Model/Update/View cycle, commands, messages, the View struct, renderer, input handling, program lifecycle, testing, component composition, integration with the Charm ecosystem (lipgloss, bubbles, huh, glamour), and production design patterns. Triggers on: "bubbletea", "bubble tea", "tea.Model", "tea.Cmd", "tea.Msg", "tea.Program", "tea.View", "tea.KeyPressMsg", "tea.WindowSizeMsg", "tea.MouseMsg", "tea.Batch", "tea.Sequence", "tea.Quit", "Elm Architecture", "charmbracelet", "Bubble Tea v2", "tea.NewProgram", "tea.Send", "tea.Tick", "tea.Every", "cursedRenderer", "ultraviolet", "ScreenBuffer", "ProgramContext", "compositor".

FileKindSize
SKILL.mdskill md9.2 KB
references/commands.mdmarkdown7.7 KB
references/composition.mdmarkdown13.4 KB
references/input-signals.mdmarkdown10.4 KB
references/messages.mdmarkdown10.4 KB
references/model-view.mdmarkdown8.8 KB
references/patterns.mdmarkdown32.3 KB
references/program.mdmarkdown10.5 KB
references/renderer.mdmarkdown11.5 KB
references/testing.mdmarkdown7.1 KB
references/v1-v2-migration.mdmarkdown10.5 KB

references/testing.md

View on GitHub
# Testing Bubble Tea Programs

In-depth reference for testing Bubble Tea programs: test patterns, program options for testing, testing commands, and testing components.

## Core Testing Pattern

Use `bytes.Buffer` for I/O and send quit from a goroutine:

```go
func TestMyProgram(t *testing.T) {
    t.Parallel()
    var buf bytes.Buffer
    var in bytes.Buffer

    m := &myModel{}
    p := tea.NewProgram(m,
        tea.WithInput(&in),
        tea.WithOutput(&buf),
    )
    go func() {
        for {
            time.Sleep(time.Millisecond)
            if m.ready.Load() {
                p.Quit()
                return
            }
        }
    }()

    if _, err := p.Run(); err != nil {
        t.Fatal(err)
    }
}
```

## Program Options for Testing

| Option | Purpose |
|--------|---------|
| `tea.WithInput(&bytes.Buffer{})` | Provide input from a buffer (no real TTY) |
| `tea.WithOutput(&bytes.Buffer{})` | Capture output to a buffer |
| `tea.WithoutSignals()` | Ignore OS signals (prevents SIGINT from killing test) |
| `tea.WithoutRenderer()` | Disable rendering entirely (non-TUI testing) |
| `tea.WithContext(ctx)` | Use cancellable context for test control |
| `tea.WithWindowSize(w, h)` | Set initial terminal size |
| `tea.WithColorProfile(p)` | Force a specific color profile |

## Testing with Context Cancellation

```go
func TestWithContext(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    p := tea.NewProgram(model, tea.WithContext(ctx))
    _, err := p.Run()
    if errors.Is(err, tea.ErrProgramKilled) {
        // Expected: context cancelled
    }
}
```

## Testing with Send

```go
func TestWithSend(t *testing.T) {
    p := tea.NewProgram(model,
        tea.WithInput(&bytes.Buffer{}),
        tea.WithOutput(&bytes.Buffer{}),
    )
    go func() {
        p.Send(customMsg{})
        p.Send(tea.Quit())
    }()
    _, err := p.Run()
    if err != nil {
        t.Fatal(err)
    }
}
```

**Note**: `p.Send()` blocks if the program hasn't started yet. Always call from a goroutine.

## Testing Commands Directly

Since `Cmd` is `func() Msg`, you can call commands directly:

```go
func TestTickCommand(t *testing.T) {
    cmd := tea.Tick(10*time.Millisecond, func(t time.Time) tea.Msg {
        return tickMsg(t)
    })
    msg := cmd()  // blocks until timer fires
    if _, ok := msg.(tickMsg); !ok {
        t.Errorf("expected tickMsg, got %T", msg)
    }
}
```

## Testing Batch and Sequence

```go
func TestBatch(t *testing.T) {
    var count atomic.Int32
    cmd := tea.Batch(
        func() tea.Msg { count.Add(1); return msg1{} },
        func() tea.Msg { count.Add(1); return msg2{} },
    )
    // Batch is a BatchMsg — need to execute through a program
    // Or test individual commands directly
}
```

## Testing Update Logic

Since `Update` is a pure function (given model + message → new model + command), you can test it directly without a `Program`:

```go
func TestUpdate(t *testing.T) {
    m := myModel{count: 0}
    newM, cmd := m.Update(tickMsg{})

    // Check state change
    if newM.(myModel).count != 1 {
        t.Errorf("expected count=1, got %d", newM.(myModel).count)
    }

    // Check command
    if cmd != nil {
        msg := cmd()
        if _, ok := msg.(tickMsg); !ok {
            t.Errorf("expected tickMsg from cmd, got %T", msg)
        }
    }
}
```

## Testing View Output

```go
func TestView(t *testing.T) {
    m := myModel{items: []string{"foo", "bar"}}
    v := m.View()

    // Check View struct fields
    if !v.AltScreen {
        t.Error("expected alt screen")
    }

    // Check content
    if !strings.Contains(v.Content, "foo") {
        t.Error("expected 'foo' in view content")
    }
}
```

## Testing with Output Capture

```go
func TestOutputCapture(t *testing.T) {
    var buf bytes.Buffer
    p := tea.NewProgram(model,
        tea.WithInput(&bytes.Buffer{}),
        tea.WithOutput(&buf),
    )
    go p.Send(tea.Quit())

    _, err := p.Run()
    if err != nil {
        t.Fatal(err)
    }

    // Check rendered output
    output := buf.String()
    if !strings.Contains(output, "expected text") {
        t.Errorf("unexpected output: %s", output)
    }
}
```

## Testing Error Conditions

```go
func TestInterrupt(t *testing.T) {
    p := tea.NewProgram(model,
        tea.WithInput(&bytes.Buffer{}),
        tea.WithOutput(&bytes.Buffer{}),
    )
    go p.Send(tea.Interrupt())

    _, err := p.Run()
    if !errors.Is(err, tea.ErrInterrupted) {
        t.Errorf("expected ErrInterrupted, got %v", err)
    }
}

func TestKill(t *testing.T) {
    p := tea.NewProgram(model,
        tea.WithInput(&bytes.Buffer{}),
        tea.WithOutput(&bytes.Buffer{}),
    )
    go p.Kill()

    _, err := p.Run()
    if !errors.Is(err, tea.ErrProgramKilled) {
        t.Errorf("expected ErrProgramKilled, got %v", err)
    }
}
```

## Testing with Filter

```go
func TestWithFilter(t *testing.T) {
    var filtered atomic.Bool
    filter := func(m tea.Model, msg tea.Msg) tea.Msg {
        if _, ok := msg.(tea.QuitMsg); ok {
            filtered.Store(true)
            return nil  // block quit
        }
        return msg
    }

    p := tea.NewProgram(model,
        tea.WithInput(&bytes.Buffer{}),
        tea.WithOutput(&bytes.Buffer{}),
        tea.WithFilter(filter),
    )
    go func() {
        p.Send(tea.Quit())
        // Quit was blocked, need to kill instead
        time.Sleep(100 * time.Millisecond)
        p.Kill()
    }()

    p.Run()
    if !filtered.Load() {
        t.Error("expected quit to be filtered")
    }
}
```

## Testing Components (Bubbles)

```go
func TestTextInput(t *testing.T) {
    ti := textinput.New()
    ti.SetValue("hello")

    // Test Update directly
    newTi, cmd := ti.Update(tea.KeyPressMsg{Code: 'a', Text: "a"})
    if newTi.Value() != "helloa" {
        t.Errorf("expected 'helloa', got %s", newTi.Value())
    }
    _ = cmd
}
```

## Test Helpers from Source

The Bubble Tea test suite uses a `testModel` struct with `atomic.Value` fields for thread-safe state checks:

```go
type testModel struct {
    executed atomic.Value
    counter atomic.Int32
}

func (m *testModel) Init() tea.Cmd { return nil }
func (m *testModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    m.executed.Store(true)
    m.counter.Add(1)
    return m, nil
}
func (m *testModel) View() tea.View {
    return tea.NewView("")
}
```

## Common Test Patterns Summary

For advanced testing patterns (direct model testing without tea.Program, version bump contracts, render hit counting, golden files, ANSI stripping), see [patterns.md](patterns.md#testing-patterns).

| Pattern | When to Use |
|---------|-------------|
| Direct `Update()` call | Testing state transitions |
| Direct `cmd()` call | Testing command results |
| `WithInput`/`WithOutput` + `go p.Quit()` | Basic integration test |
| `WithContext` + `cancel()` | Test cancellation/shutdown |
| `WithFilter` | Test message filtering |
| `WithoutRenderer` | Test non-TUI logic |
| `WithWindowSize` | Test resize handling |
| `p.Send(msg)` from goroutine | Test specific message handling |
| `p.Kill()` | Test forced shutdown |
| Output buffer inspection | Test rendered output |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall