Crawler

Package crawler provides black-box testing for terminal user interfaces. crawler runs a real binary inside an isolated tmux server, sends keystrokes, captures screen output, and performs assertions through the standard testing.TB interface. It is framework-agnostic and works with any program that renders in a terminal. Cleanup is automatic through t.Cleanup; there is no Close method. Open creates a dedicated tmux server for each test, using a unique socket path under os.TempDir. This gives subtests and parallel tests full isolation. Internally, crawler starts tmux with a temporary config file that enables: The tmux server is torn down with kill-server during cleanup. Terminal.WaitFor and Terminal.WaitForScreen poll until a Matcher succeeds or a timeout expires. This is the core reliability mechanism and avoids ad hoc sleeps in tests. Wait behavior: Built-in matchers include Text, Regexp, Line, LineContains, Not, All, Any, Empty, and Cursor. Terminal.Screen captures the visible pane. Terminal.Scrollback captures full scrollback history. A Screen is immutable and provides helpers such as Screen.String, Screen.Lines, Screen.Line, Screen.Contains, and Screen.Size. Terminal.MatchSnapshot and Screen.MatchSnapshot compare screen content to golden files under testdata. Set CRAWLER_UPDATE=1 to create or update golden files. Snapshot content is normalized for stable diffs by trimming trailing spaces, trimming trailing blank lines, and writing a single trailing newline. On wait failures, crawler reports: This keeps failures actionable without extra debug tooling. tmux is resolved in this order: