teatest

Crystal port of Go teatest library
Test Bubbletea programs easily, including golden files

Architecture · Development · Guidelines · Testing · PR Workflow · Porting Parity

Test helpers for Term2 programs. This is a Crystal port of the Go x/exp/teatest/v2 package from charmbracelet/ansi.

Quick Start

1. Add the dependency to your shard.yml:

dependencies:
  teatest:
    github: dsisnero/teatest

2. Run shards install

3. Use in your tests:

require "teatest"
require "term2"

class Counter
  include Term2::Model

  def initialize(@n : Int32 = 0)
  end

  def init : Term2::Cmd
    Term2::Cmds.none
  end

  def update(msg : Term2::Msg) : {Term2::Model, Term2::Cmd}
    case msg
    when Term2::KeyMsg
      if msg.code == Ultraviolet::KeyEnter
        return {self, nil}
      end
    end
    {self, nil}
  end

  def view : String
    "count=#{@n}\n"
  end
end

tm = Teatest.new_test_model(Counter.new)
Teatest.wait_for(tm.output, ->(b : Bytes) { String.new(b).includes?("count=") })
tm.quit

Features

• Golden file testing: Compare output with expected golden files
• Async testing: Wait for specific output patterns
• Term2 integration: Test Bubble Tea applications
• Go parity: Behavior matches upstream Go x/exp/teatest/v2
• ANSI handling: Proper terminal escape sequence support

Development

# Install dependencies
make install

# Run tests
make test

# Check code quality
make format
make lint

See Development Guide for full setup instructions.

Documentation

Contributing

1. Create an issue: /forge-create-issue
2. Implement: /forge-implement-issue <number>
3. Self-review: /forge-reflect-pr
4. Address feedback: /forge-address-pr-feedback
5. Update changelog: /forge-update-changelog