Documentation
¶
Overview ¶
Package tuitest is a black-box end-to-end harness for the docker-agent TUI.
It drives the real top-level Bubble Tea model through a real tea.Program so that the full event path — keyboard input, the chat page, the runtime event stream, and the session supervisor that routes events back via program.Send — is exercised exactly as in production. The only thing it fakes is the terminal: the renderer is disabled and each rendered frame is captured inside the model's Update (which runs on the program's single message-loop goroutine), so frame capture is race-free and independent of renderer timing.
The result is a fluent, Selenium-like DSL without Selenium's flakiness:
tuitest.New(t, model, 120, 40).
Type("What's 2+2?").
Enter().
WaitFor(tuitest.Contains("4")).
AssertGolden("basic_math")
Synchronization is expressed through WaitFor: it polls the latest captured frame until a Matcher passes or a deadline elapses. Because runtime events arrive asynchronously (the agent streams its answer), tests wait for visible outcomes rather than sleeping.
Index ¶
- type Driver
- func (d *Driver) Assert(m Matcher) *Driver
- func (d *Driver) AssertClipboard(m Matcher) *Driver
- func (d *Driver) AssertGolden(name string) *Driver
- func (d *Driver) Click(x, y int) *Driver
- func (d *Driver) ClickText(text string) *Driver
- func (d *Driver) Clipboard() string
- func (d *Driver) Drag(fromX, fromY, toX, toY int) *Driver
- func (d *Driver) Enter() *Driver
- func (d *Driver) FindText(text string) (x, y int, ok bool)
- func (d *Driver) Frame() string
- func (d *Driver) MoveMouse(x, y int) *Driver
- func (d *Driver) MoveMouseToText(text string) *Driver
- func (d *Driver) MustFindText(text string) (x, y int)
- func (d *Driver) Press(code rune, mods ...tea.KeyMod) *Driver
- func (d *Driver) Resize(width, height int) *Driver
- func (d *Driver) Send(msg tea.Msg) *Driver
- func (d *Driver) Type(s string) *Driver
- func (d *Driver) WaitFor(m Matcher) *Driver
- func (d *Driver) WaitForClipboard(substr string) *Driver
- func (d *Driver) WaitForStable(quiet time.Duration) *Driver
- type Matcher
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Driver ¶
type Driver struct {
// contains filtered or unexported fields
}
Driver drives a TUI model and exposes a fluent assertion API. Every method that advances state returns the Driver so calls can be chained. Assertion failures are reported through testing.TB and stop the test.
func New ¶
New starts model in a real, renderer-less tea.Program and returns a Driver. width and height seed the initial window size. The program is stopped and awaited automatically via t.Cleanup, and a model implementing Shutdown has its resources released right after.
model is typically the value returned by tui.New. If it implements SetProgram (as the docker-agent TUI does) the running program is wired into it so the session supervisor can deliver routed runtime events.
func (*Driver) AssertClipboard ¶
AssertClipboard immediately checks the latest copied text with m.
func (*Driver) AssertGolden ¶
AssertGolden compares the latest frame against the golden file testdata/<name>.golden. With -tuitest.update the golden file is (re)written from the current frame, which is how you record or refresh a snapshot after an intentional UI change.
Goldens are the regression net for "we didn't mean to change the finished product": any unintended visual drift in a covered screen turns into a diff.
func (*Driver) Clipboard ¶
Clipboard returns the latest text copied through the TUI's clipboard path. The tuitest driver installs a spy so tests never touch the real system clipboard.
func (*Driver) Drag ¶ added in v1.102.0
Drag presses the left button at (fromX, fromY), moves through a midpoint, and releases at (toX, toY).
func (*Driver) FindText ¶
FindText returns the coordinates of the first occurrence of text in the latest captured frame. The x coordinate is display width, not byte offset, so it works for wide Unicode before the matched text.
func (*Driver) MoveMouseToText ¶
MoveMouseToText moves the mouse to the first visible occurrence of text.
func (*Driver) MustFindText ¶
MustFindText is like FindText but fails the test when text is not visible.
func (*Driver) Press ¶
Press sends a single key by its code (e.g. tea.KeyEnter, tea.KeyEsc) with optional modifiers.
func (*Driver) Send ¶
Send delivers an arbitrary message to the model. Useful for injecting runtime events or custom messages a scenario can't reach through the keyboard alone.
func (*Driver) WaitFor ¶
WaitFor polls the latest frame until m passes or the timeout elapses. On timeout it fails the test with the last frame for context.
func (*Driver) WaitForClipboard ¶
WaitForClipboard polls until the latest copied text contains substr, or the driver's timeout elapses.
type Matcher ¶
type Matcher interface {
// contains filtered or unexported methods
}
Matcher tests a captured frame. Matchers are the vocabulary WaitFor and Assert speak; they replace Selenium's brittle selectors with simple, composable predicates over the rendered text.
func Absent ¶
Absent matches when the frame does NOT contain substr. Pair it with a prior WaitFor on something positive, since "absent" is trivially true before the UI has rendered anything.
func ContainsAll ¶
ContainsAll matches when the frame contains every substring.
Source Files