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) 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.
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) 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