steep

package module
v0.0.0-...-47e0271 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 14, 2026 License: MIT Imports: 27 Imported by: 0

README

banner

TODO

Documentation

Overview

Package steep provides test helpers for tea.Program and models (root and component).

Use NewHarness to run a root tea.Model in a test: 

h := steep.NewHarness(t, model, steep.WithWindowSize(80, 24))
h.Type("hello").WaitSettle().AssertString("hello")
h.QuitProgram()
h.WaitFinished()

Use NewComponentHarness for components that expose View() string and an Update method through the asynchronous tea.Program runtime.

Index

Constants

View Source 
const (
	// DefaultTermWidth is the default terminal width for [NewHarness] and
	// [NewComponentHarness] (the [tea.Program] window and vt emulator).
	DefaultTermWidth = 80
	// DefaultTermHeight is the default terminal height for [NewHarness] and
	// [NewComponentHarness] (the [tea.Program] window and vt emulator).
	DefaultTermHeight = 24

	// DefaultTimeout is the default timeout used by [Harness] blocking waits.
	DefaultTimeout = 2 * time.Second
	// DefaultCheckInterval is the default polling interval used by [Harness] waits.
	DefaultCheckInterval = 10 * time.Millisecond
	// DefaultSettleTimeout is the default settle timeout used by [Harness] settle
	// waits. This must be less than 80% of the timeout set by [WithTimeout].
	DefaultSettleTimeout = 100 * time.Millisecond
)

Variables

This section is empty.

Functions

func AssertDimensions 

func AssertDimensions(tb testing.TB, view Viewable, width, height int, opts ...Option) bool

AssertDimensions reports an error unless output has specified dimensions.

See also Harness.AssertDimensions, AssertWidth, AssertHeight, Dimensions, RequireDimensions, and WithANSI.

func AssertHasMessage 

func AssertHasMessage[T uv.Event](tb testing.TB, log MessageCollector, opts ...Option) bool

AssertHasMessage asserts that at least one message with the same concrete type as T has been observed.

func AssertHeight 

func AssertHeight(tb testing.TB, view Viewable, n int, opts ...Option) bool

AssertHeight reports an error unless output has n rows. Note that this behaves differently to charm.land/lipgloss/v2.Height which always assumes a minimum height of 1. It returns whether the output matched and allows the test to continue.

See also Harness.AssertHeight, AssertDimensions, AssertWidth, Dimensions, and RequireHeight.

func AssertMatch 

func AssertMatch(tb testing.TB, view Viewable, pattern string, opts ...Option) bool

AssertMatch reports an error unless output matches the regular expression pattern. pattern is compiled with regexp.Compile; a compile error fails the test immediately. It returns whether the output matched and allows the test to continue.

See also Harness.AssertMatch, WaitMatch, AssertNotMatch, and RequireMatch.

func AssertNotMatch 

func AssertNotMatch(tb testing.TB, view Viewable, pattern string, opts ...Option) bool

AssertNotMatch reports an error if output matches the regular expression pattern. pattern is compiled with regexp.Compile; a compile error fails the test immediately. It returns whether the output matched and allows the test to continue.

See also Harness.AssertNotMatch, AssertMatch, WaitNotMatch, and RequireNotMatch.

func AssertNotString 

func AssertNotString(tb testing.TB, view Viewable, content string, opts ...Option) bool

AssertNotString reports an error if content appears in output. It returns whether the output matched and allows the test to continue.

See also Harness.AssertNotString, AssertString, AssertNotStrings, and WaitNotString.

func AssertNotStrings 

func AssertNotStrings(tb testing.TB, view Viewable, contents []string, opts ...Option) bool

AssertNotStrings reports an error if any substring in contents appears in output. It returns whether the output matched and allows the test to continue.

See also Harness.AssertNotStrings, AssertStrings, AssertNotString, WaitStrings, and WaitNotStrings.

func AssertString 

func AssertString(tb testing.TB, view Viewable, content string, opts ...Option) bool

AssertString reports an error unless content appears in output. It returns whether the output matched and allows the test to continue.

See also Harness.AssertString, AssertStrings, AssertNotString, and WaitString.

func AssertStrings 

func AssertStrings(tb testing.TB, view Viewable, contents []string, opts ...Option) bool

AssertStrings reports an error unless every substring in contents appears in output. It returns whether the output matched and allows the test to continue.

See also Harness.AssertStrings, AssertString, RequireStrings, and WaitStrings.

func AssertWidth 

func AssertWidth(tb testing.TB, view Viewable, n int, opts ...Option) bool

AssertWidth reports an error unless output has n columns. It returns whether the output matched and allows the test to continue.

See also Harness.AssertWidth, AssertDimensions, Dimensions, AssertHeight, and RequireWidth.

func Dimensions 

func Dimensions(out string, opts ...Option) (w, h int)

Dimensions returns the width and height of the output.

See also AssertDimensions, AssertWidth, AssertHeight, and Harness.AssertDimensions.

func FilterMessagesFunc 

func FilterMessagesFunc[T uv.Event](tb testing.TB, messages iter.Seq[uv.Event], fn func(T) bool) iter.Seq[T]

FilterMessagesFunc filters an iterator of messages to only include messages that return true from the provided "fn" function.

func FilterMessagesType 

func FilterMessagesType[T uv.Event](tb testing.TB, messages iter.Seq[uv.Event]) iter.Seq[T]

FilterMessagesType filters an iterator of messages to only include messages with the same concrete type as T.

func IgnoreMessagesReflect 

func IgnoreMessagesReflect(tb testing.TB, messages iter.Seq[uv.Event], ignore ...reflect.Type) iter.Seq[uv.Event]

IgnoreMessagesReflect filters an iterator of messages to exclude messages with the same concrete type as any of the provided reflect.Types.

func RequireDimensions 

func RequireDimensions(tb testing.TB, view Viewable, width, height int, opts ...Option)

RequireDimensions fails the test immediately unless output has specified dimensions.

See also Harness.RequireDimensions, AssertDimensions, RequireHeight, RequireWidth, and Harness.AssertSnapshot.

func RequireHasMessage 

func RequireHasMessage[T uv.Event](tb testing.TB, log MessageCollector, opts ...Option)

RequireHasMessage requires that at least one message with the same concrete type as T has been observed.

func RequireHeight 

func RequireHeight(tb testing.TB, view Viewable, n int, opts ...Option)

RequireHeight fails the test immediately unless output has n rows.

See also Harness.RequireHeight, AssertHeight, and RequireDimensions.

func RequireMatch 

func RequireMatch(tb testing.TB, view Viewable, pattern string, opts ...Option)

RequireMatch fails the test immediately unless output matches the regular expression pattern.

See also Harness.RequireMatch, AssertMatch, RequireNotMatch, and WaitMatch.

func RequireNotMatch 

func RequireNotMatch(tb testing.TB, view Viewable, pattern string, opts ...Option)

RequireNotMatch fails the test immediately if output matches the regular expression pattern.

See also Harness.RequireNotMatch, AssertNotMatch, and RequireMatch.

func RequireNotString 

func RequireNotString(tb testing.TB, view Viewable, content string, opts ...Option)

RequireNotString fails the test immediately if content appears in output.

See also Harness.RequireNotString, AssertNotString, RequireString, AssertNotStrings, and RequireNotStrings.

func RequireNotStrings 

func RequireNotStrings(tb testing.TB, view Viewable, contents []string, opts ...Option)

RequireNotStrings fails the test immediately if any substring in contents appears in output.

See also Harness.RequireNotStrings, AssertNotStrings, RequireStrings, and RequireNotString.

func RequireString 

func RequireString(tb testing.TB, view Viewable, content string, opts ...Option)

RequireString fails the test immediately unless content appears in output.

See also Harness.RequireString, AssertString, and RequireStrings.

func RequireStrings 

func RequireStrings(tb testing.TB, view Viewable, contents []string, opts ...Option)

RequireStrings fails the test immediately unless every substring in contents appears in output.

See also Harness.RequireStrings, AssertStrings, and RequireString.

func RequireWidth 

func RequireWidth(tb testing.TB, view Viewable, n int, opts ...Option)

RequireWidth fails the test immediately unless output has n columns.

See also Harness.RequireWidth, AssertWidth, and RequireDimensions.

func WaitBytes 

func WaitBytes(tb testing.TB, model Viewable, contents []byte, opts ...Option) []byte

WaitBytes waits until output contains contents.

See also Harness.WaitBytes, WaitViewFunc, WaitStrings, and WaitNotBytes.

func WaitLiveMessage 

func WaitLiveMessage[T uv.Event](tb testing.TB, log MessageCollector, opts ...Option) T

WaitLiveMessage waits until a NEW message (only messages received since this function was invoked) with the same concrete type as T has been observed, then returns the first match.

func WaitLiveMessageWhere 

func WaitLiveMessageWhere(tb testing.TB, log MessageCollector, fn func(uv.Event) (ok bool), opts ...Option) uv.Event

WaitLiveMessageWhere waits until "fn" returns true for a NEW message (only messages received since this function was invoked).

See also WaitMessageWhere.

func WaitMatch 

func WaitMatch(tb testing.TB, model Viewable, pattern string, opts ...Option) string

WaitMatch waits until the latest view output matches the regular expression pattern. pattern is compiled with regexp.Compile; a compile error fails the test immediately.

See also Harness.WaitMatch, AssertMatch, WaitNotMatch, and RequireMatch.

func WaitMessage 

func WaitMessage[T uv.Event](tb testing.TB, log MessageCollector, opts ...Option) T

WaitMessage waits until at least one message with the same concrete type as T has been observed, then returns the first match.

func WaitMessageWhere 

func WaitMessageWhere(tb testing.TB, log MessageCollector, fn func(uv.Event) (ok bool), opts ...Option) uv.Event

WaitMessageWhere waits until "fn" returns true for a message (across all received messages).

See also WaitLiveMessageWhere.

func WaitNotBytes 

func WaitNotBytes(tb testing.TB, model Viewable, contents []byte, opts ...Option) []byte

WaitNotBytes waits until output contains none of the contents.

See also Harness.WaitNotBytes, WaitBytes, and WaitStrings.

func WaitNotMatch 

func WaitNotMatch(tb testing.TB, model Viewable, pattern string, opts ...Option) string

WaitNotMatch waits until the latest view output does not match the regular expression pattern. pattern is compiled with regexp.Compile; a compile error fails the test immediately.

See also Harness.WaitNotMatch, WaitMatch, AssertNotMatch, and RequireNotMatch.

func WaitNotString 

func WaitNotString(tb testing.TB, model Viewable, contents string, opts ...Option) string

WaitNotString waits until output contains none of the contents.

See also Harness.WaitNotString, WaitString, and WaitNotStrings.

func WaitNotStrings 

func WaitNotStrings(tb testing.TB, model Viewable, contents []string, opts ...Option) string

WaitNotStrings waits until output contains none of the contents.

See also Harness.WaitNotStrings, WaitStrings, and WaitNotString.

func WaitSettle 

func WaitSettle(tb testing.TB, view Viewable, opts ...Option)

WaitSettle waits until the rendered view string has not changed for the configured settle timeout. The model must implement Viewable; each check calls View() and compares the string to the previous sample.

See also Harness.WaitSettle, Harness.WaitSettleMessages, WithSettle, WithCheck, and WithTimeout.

func WaitSettleMessages 

func WaitSettleMessages(tb testing.TB, log MessageCollector, opts ...Option)

WaitSettleMessages waits until no messages have been observed for the configured settle timeout.

See also Harness.WaitSettleMessages, WaitSettle, WithSettle, WithCheck, and WithTimeout.

func WaitString 

func WaitString(tb testing.TB, model Viewable, contents string, opts ...Option) string

WaitString waits until output contains contents.

See also Harness.WaitString, WaitViewFunc, WaitStrings, and WaitNotString.

func WaitStrings 

func WaitStrings(tb testing.TB, model Viewable, contents []string, opts ...Option) string

WaitStrings waits until output contains all contents.

See also Harness.WaitStrings, WaitString, and WaitNotStrings.

func WaitViewFunc 

func WaitViewFunc[T ~string | ~[]byte](
	tb testing.TB,
	view Viewable,
	condition func(view T) bool,
	opts ...Option,
) T

WaitViewFunc waits until condition returns true for the latest view output.

See also Harness.WaitBytesFunc, Harness.WaitStringFunc, WaitBytes, WaitMatch, and WaitStrings.

Types

type Harness 

type Harness struct {
	// contains filtered or unexported fields
}

Harness is a test harness for a tea.Program.

func Mutate 

func Mutate[M any](h *Harness, fn func(M) M, opts ...Option) *Harness

Mutate applies fn to the current underlying model from within the tea.Program's Update handling. This should be used sparingly, and only when necessary to test a specific scenario that is otherwise not possible or would pollute your model with unnecessary state. It uses the testing.TB from NewHarness or NewComponentHarness (generics cannot be expressed as a method on Harness).

fn should use the same model type originally passed to NewHarness or NewComponentHarness, such as func(Model) Model or func(*Model) *Model.

func NewComponentHarness 

func NewComponentHarness[M any](tb testing.TB, model M, opts ...Option) *Harness

NewComponentHarness creates a test harness for a component model by wrapping it in a root tea.Model and running it inside a tea.Program.

func NewHarness 

func NewHarness(tb testing.TB, model tea.Model, opts ...Option) *Harness

NewHarness creates a test harness by running the root tea.Model in a tea.Program. The harness captures rendered terminal output and exposes helpers for driving and asserting on runtime behavior.

func (*Harness) AssertDimensions 

func (h *Harness) AssertDimensions(width, height int, opts ...Option) *Harness

AssertDimensions reports an error unless view output has width columns and height rows. It allows the test to continue.

See also AssertDimensions, Harness.RequireDimensions, Harness.AssertWidth, Harness.AssertHeight, Harness.RequireSnapshot, and Dimensions.

func (*Harness) AssertHeight 

func (h *Harness) AssertHeight(height int, opts ...Option) *Harness

AssertHeight reports an error unless view output has height rows. It allows the test to continue.

See also AssertHeight, Harness.RequireHeight, Harness.AssertDimensions, Harness.AssertWidth, AssertDimensions, and Dimensions.

func (*Harness) AssertJSON 

func (h *Harness) AssertJSON(opts ...snapshot.Option) *Harness

AssertJSON compares the current terminal screen buffer in JSON format against a previously captured snapshot. It allows the test to continue.

See also Harness.AssertSnapshot.

func (*Harness) AssertMatch 

func (h *Harness) AssertMatch(pattern string, opts ...Option) *Harness

AssertMatch reports an error unless view output matches the regular expression pattern.

See also AssertMatch, Harness.RequireMatch, Harness.WaitMatch, Harness.AssertNotMatch, Harness.RequireNotMatch, and Harness.WaitNotMatch.

func (*Harness) AssertNotMatch 

func (h *Harness) AssertNotMatch(pattern string, opts ...Option) *Harness

AssertNotMatch reports an error if view output matches the regular expression pattern.

See also AssertNotMatch, Harness.RequireNotMatch, Harness.AssertMatch, Harness.RequireMatch, and Harness.WaitNotMatch.

func (*Harness) AssertNotString 

func (h *Harness) AssertNotString(content string, opts ...Option) *Harness

AssertNotString reports an error if content appears in view output. It allows the test to continue.

See also AssertNotString, Harness.AssertString, Harness.AssertNotStrings, and Harness.WaitNotString.

func (*Harness) AssertNotStrings 

func (h *Harness) AssertNotStrings(contents []string, opts ...Option) *Harness

AssertNotStrings reports an error if any substring in contents appears in view output. It allows the test to continue.

See also AssertNotStrings, Harness.AssertStrings, AssertNotString, and WaitNotStrings.

func (*Harness) AssertSnapshot 

func (h *Harness) AssertSnapshot(opts ...snapshot.Option) *Harness

AssertSnapshot compares the current terminal screen buffer against a snapshot file. It allows the test to continue.

See also Harness.RequireSnapshot.

func (*Harness) AssertString 

func (h *Harness) AssertString(content string, opts ...Option) *Harness

AssertString reports an error unless content appears in view output. It allows the test to continue.

See also AssertString, Harness.RequireString, Harness.AssertStrings, and Harness.WaitString.

func (*Harness) AssertStrings 

func (h *Harness) AssertStrings(contents []string, opts ...Option) *Harness

AssertStrings reports an error unless every substring in contents appears in view output. It allows the test to continue.

See also AssertStrings, Harness.AssertString, Harness.RequireStrings, and WaitStrings.

func (*Harness) AssertWidth 

func (h *Harness) AssertWidth(width int, opts ...Option) *Harness

AssertWidth reports an error unless view output has width columns. It allows the test to continue.

See also AssertWidth, Harness.RequireWidth, Harness.AssertDimensions, Harness.AssertHeight, AssertDimensions, and Dimensions.

func (*Harness) BgColor 

func (h *Harness) BgColor() color.Color

BgColor returns the terminal emulator's background color.

func (*Harness) Blur 

func (h *Harness) Blur() *Harness

Blur sends the terminal a blur event if focus events mode is enabled. This is the opposite of Harness.Focus.

func (*Harness) Bounds 

func (h *Harness) Bounds() uv.Rectangle

Bounds returns the terminals current screen bounds.

func (*Harness) ClearScrollback 

func (h *Harness) ClearScrollback() *Harness

ClearScrollback clears all scrollback history on the screen buffer.

func (*Harness) Close 

func (h *Harness) Close()
func (h *Harness) CursorBlink() bool

CursorBlink reports whether blinking is enabled for the tracked cursor style.

func (*Harness) CursorColor 

func (h *Harness) CursorColor() color.Color

CursorColor returns the terminal emulator's cursor color.

func (*Harness) CursorPosition 

func (h *Harness) CursorPosition() uv.Position

CursorPosition returns the terminal emulator cursor position.

func (*Harness) CursorStyle 

func (h *Harness) CursorStyle() vt.CursorStyle

CursorStyle returns the tracked VT cursor shape.

func (*Harness) CursorVisible 

func (h *Harness) CursorVisible() bool

CursorVisible reports whether the cursor is visible per the last vt.Callbacks.CursorVisibility update (driven by DECTCEM and related screen switches).

func (*Harness) Dimensions 

func (h *Harness) Dimensions() (width, height int)

Dimensions returns the terminals width and height in cells.

func (*Harness) FgColor 

func (h *Harness) FgColor() color.Color

FgColor returns the terminal emulator's foreground color.

func (*Harness) FinalModel 

func (h *Harness) FinalModel(opts ...Option) tea.Model

FinalModel waits for the tea.Program to finish and returns the latest underlying root model.

func (*Harness) Focus 

func (h *Harness) Focus() *Harness

Focus sends the terminal a focus event if focus events mode is enabled. This is the opposite of Harness.Blur.

func (*Harness) Height 

func (h *Harness) Height() int

Height returns the terminals current height in cells (matches Harness.View row count).

func (*Harness) IsAltScreen 

func (h *Harness) IsAltScreen() bool

IsAltScreen returns true if the terminal is in alt screen mode.

func (*Harness) IsFocused 

func (h *Harness) IsFocused() bool

IsFocused reports the last known terminal focus state.

func (*Harness) Key 

func (h *Harness) Key(key string) *Harness

Key sends a single key press message to the terminal emulator itself, e.g. "ctrl+a", "enter", "space", etc.

Note that as this sends through the emulator, if paired with Harness.SendProgram, The order of events that the tea.Program receives may not be the same as order of invocation.

func (*Harness) KeyBackspace 

func (h *Harness) KeyBackspace() *Harness

KeyBackspace sends a backspace key press to the terminal emulator.

func (*Harness) KeyCtrlC 

func (h *Harness) KeyCtrlC() *Harness

KeyCtrlC sends ctrl+c to the terminal emulator.

func (*Harness) KeyCtrlD 

func (h *Harness) KeyCtrlD() *Harness

KeyCtrlD sends ctrl+d to the terminal emulator.

func (*Harness) KeyDelete 

func (h *Harness) KeyDelete() *Harness

KeyDelete sends a delete (forward-delete) key press to the terminal emulator.

func (*Harness) KeyDown 

func (h *Harness) KeyDown() *Harness

KeyDown sends a down-arrow key press to the terminal emulator.

func (*Harness) KeyEsc 

func (h *Harness) KeyEsc() *Harness

KeyEsc sends an escape key press to the terminal emulator.

func (*Harness) KeyLeft 

func (h *Harness) KeyLeft() *Harness

KeyLeft sends a left-arrow key press to the terminal emulator.

func (*Harness) KeyRight 

func (h *Harness) KeyRight() *Harness

KeyRight sends a right-arrow key press to the terminal emulator.

func (*Harness) KeyUp 

func (h *Harness) KeyUp() *Harness

KeyUp sends an up-arrow key press to the terminal emulator.

func (*Harness) LastBellAt 

func (h *Harness) LastBellAt() time.Time

LastBellAt returns the wall clock time of the most recent bell (ansi.BEL) processed by the VT emulator. It is the zero time.Time until the first bell.

func (*Harness) LeftClick 

func (h *Harness) LeftClick(x, y int) *Harness

LeftClick is Harness.MouseClick with the left mouse button.

func (*Harness) LeftDrag 

func (h *Harness) LeftDrag(x1, y1, x2, y2 int) *Harness

LeftDrag is Harness.MouseDrag with the left mouse button.

func (*Harness) LiveMessages 

func (h *Harness) LiveMessages(ctx context.Context) iter.Seq[uv.Event]

LiveMessages returns a new iterator to live messages observed by the underlying model, starting from the first message observed after the call returns.

func (*Harness) MessageHistory 

func (h *Harness) MessageHistory() iter.Seq[uv.Event]

MessageHistory returns a copy of all messages observed by the underlying model.

func (*Harness) Messages 

func (h *Harness) Messages(ctx context.Context) iter.Seq[uv.Event]

Messages returns a iterator to all (historical and live) messages observed by the underlying model.

func (*Harness) MiddleClick 

func (h *Harness) MiddleClick(x, y int) *Harness

MiddleClick is Harness.MouseClick with the middle mouse button.

func (*Harness) ModeSetting 

func (h *Harness) ModeSetting(mode ansi.Mode) ansi.ModeSetting

ModeSetting returns the tracked ANSI mode setting. An absent mode yields ansi.ModeNotRecognized.

func (*Harness) Mouse 

func (h *Harness) Mouse(m uv.MouseEvent) *Harness

Mouse forwards a mouse event through the terminal emulator. The running tea.Program must have enabled a mouse tracking mode and (typically) SGR mouse encoding; otherwise events are discarded by the emulator, matching real terminal behavior.

func (*Harness) MouseClick 

func (h *Harness) MouseClick(button uv.MouseButton, x, y int) *Harness

MouseClick simulates a full press and release at (x, y).

func (*Harness) MouseDrag 

func (h *Harness) MouseDrag(button uv.MouseButton, x1, y1, x2, y2 int) *Harness

MouseDrag simulates a drag from (x1, y1) to (x2, y2).

func (*Harness) Paste 

func (h *Harness) Paste(text string) *Harness

Paste paste text into the terminal. If bracketed paste mode is enabled, the text is bracketed with the appropriate escape sequences.

func (*Harness) QuitProgram 

func (h *Harness) QuitProgram() *Harness

QuitProgram requests a graceful shutdown of the tea.Program.

func (*Harness) RequireDimensions 

func (h *Harness) RequireDimensions(width, height int, opts ...Option) *Harness

RequireDimensions fails the test immediately unless view output has width columns and height rows.

See also RequireDimensions, Harness.AssertDimensions, Harness.RequireHeight, Harness.RequireWidth, and Harness.RequireSnapshot.

func (*Harness) RequireHeight 

func (h *Harness) RequireHeight(height int, opts ...Option) *Harness

RequireHeight fails the test immediately unless view output has height rows.

See also RequireHeight, Harness.AssertHeight, Harness.RequireDimensions, and AssertDimensions.

func (*Harness) RequireJSON 

func (h *Harness) RequireJSON(opts ...snapshot.Option) *Harness

RequireJSON compares the current terminal screen buffer in JSON format against a previously captured snapshot. It fails the test immediately if the snapshot does not match.

See also Harness.AssertJSON.

func (*Harness) RequireMatch 

func (h *Harness) RequireMatch(pattern string, opts ...Option) *Harness

RequireMatch fails the test immediately unless view output matches the regular expression pattern.

See also RequireMatch, Harness.AssertMatch, Harness.RequireNotMatch, and Harness.WaitMatch.

func (*Harness) RequireNotMatch 

func (h *Harness) RequireNotMatch(pattern string, opts ...Option) *Harness

RequireNotMatch fails the test immediately if view output matches the regular expression pattern.

See also RequireNotMatch, Harness.AssertNotMatch, Harness.AssertMatch, Harness.RequireMatch, and Harness.WaitNotMatch.

func (*Harness) RequireNotString 

func (h *Harness) RequireNotString(content string, opts ...Option) *Harness

RequireNotString fails the test immediately if content appears in view output.

See also RequireNotString, Harness.RequireString, AssertNotString, Harness.RequireNotStrings, and Harness.WaitNotStrings.

func (*Harness) RequireNotStrings 

func (h *Harness) RequireNotStrings(contents []string, opts ...Option) *Harness

RequireNotStrings fails the test immediately if any substring in contents appears in view output.

See also RequireNotStrings, Harness.RequireStrings, AssertNotStrings, Harness.RequireNotString, and WaitStrings.

func (*Harness) RequireSnapshot 

func (h *Harness) RequireSnapshot(opts ...snapshot.Option) *Harness

RequireSnapshot compares the current terminal screen buffer against a snapshot file. It fails the test immediately if the snapshot does not match.

See also Harness.AssertSnapshot.

func (*Harness) RequireString 

func (h *Harness) RequireString(content string, opts ...Option) *Harness

RequireString fails the test immediately unless content appears in view output.

See also RequireString, Harness.AssertString, Harness.RequireStrings, and WaitString.

func (*Harness) RequireStrings 

func (h *Harness) RequireStrings(contents []string, opts ...Option) *Harness

RequireStrings fails the test immediately unless every substring in contents appears in view output.

See also RequireStrings, Harness.RequireString, AssertStrings, and WaitStrings.

func (*Harness) RequireWidth 

func (h *Harness) RequireWidth(width int, opts ...Option) *Harness

RequireWidth fails the test immediately unless view output has width columns.

See also RequireWidth, Harness.AssertWidth, Harness.RequireDimensions, and AssertDimensions.

func (*Harness) Resize 

func (h *Harness) Resize(width, height int) *Harness

Resize resizes the terminal to the given width and height. This should result in a tea.WindowSizeMsg being sent to the tea.Program.

func (*Harness) RightClick 

func (h *Harness) RightClick(x, y int) *Harness

RightClick is Harness.MouseClick with the right mouse button.

func (*Harness) Scrollback 

func (h *Harness) Scrollback() []uv.Line

Scrollback returns a copy of the terminals scrollback lines (oldest first). It is nil in alternate screen mode. An empty non-nil slice means the scrollback buffer exists but has no lines yet.

func (*Harness) ScrollbackCount 

func (h *Harness) ScrollbackCount() int

ScrollbackCount returns the count of scrollback lines.

func (*Harness) SendProgram 

func (h *Harness) SendProgram(msg uv.Event) *Harness

SendProgram sends msg (tea.Msg or uv.Event, either works) to the tea.Program.

func (*Harness) SetBgColor 

func (h *Harness) SetBgColor(c color.Color) *Harness

SetBgColor sets the terminal emulator background color.

func (*Harness) SetCursorColor 

func (h *Harness) SetCursorColor(c color.Color) *Harness

SetCursorColor sets the terminal emulator cursor color.

func (*Harness) SetDefaultBgColor 

func (h *Harness) SetDefaultBgColor(c color.Color) *Harness

SetDefaultBgColor sets default background color used when none is specified.

func (*Harness) SetDefaultCursorColor 

func (h *Harness) SetDefaultCursorColor(c color.Color) *Harness

SetDefaultCursorColor sets default cursor color used when none is specified.

func (*Harness) SetDefaultFgColor 

func (h *Harness) SetDefaultFgColor(c color.Color) *Harness

SetDefaultFgColor sets default foreground color used when none is specified.

func (*Harness) SetFgColor 

func (h *Harness) SetFgColor(c color.Color) *Harness

SetFgColor sets the terminal emulator foreground color.

func (*Harness) SetScrollbackSize 

func (h *Harness) SetScrollbackSize(maxLines int) *Harness

SetScrollbackSize sets maximum scrollback lines retained on the terminals screen buffer.

func (*Harness) Title 

func (h *Harness) Title() string

Title returns the last known window title.

func (*Harness) Type 

func (h *Harness) Type(s string) *Harness

Type sends a sequence of key press messages to the terminal emulator itself. This is designed for providing regular text input, not more complex key combinations (ctrl-key, alt-key, etc).

Note that as this sends through the emulator, if paired with Harness.SendProgram, The order of events that the tea.Program receives may not be the same as order of invocation.

func (*Harness) View 

func (h *Harness) View() string

View returns the current VT screen buffer (vt.Emulator.Render). Harness wait, assert, and snapshot helpers sample this rendered output. Match the terminal dimensions (WithWindowSize, Harness.Resize) to the layout under test so output has no unused rows or columns beyond what the renderer emits for that window size.

func (*Harness) WaitBytes 

func (h *Harness) WaitBytes(contents []byte, opts ...Option) *Harness

WaitBytes waits until view output contains contents.

See also WaitBytes, Harness.WaitString, Harness.WaitStrings, and Harness.WaitBytesFunc.

func (*Harness) WaitBytesFunc 

func (h *Harness) WaitBytesFunc(condition func(view []byte) bool, opts ...Option) *Harness

WaitBytesFunc waits until condition returns true for the latest view output. It wraps WaitViewFunc with a byte-slice predicate.

See also Harness.WaitStringFunc, WaitBytes, WaitNotBytes, and WaitStrings.

func (*Harness) WaitFinished 

func (h *Harness) WaitFinished(opts ...Option)

WaitFinished waits for the tea.Program to finish.

See also Harness.FinalModel and Harness.WaitSettleMessages.

func (*Harness) WaitMatch 

func (h *Harness) WaitMatch(pattern string, opts ...Option) *Harness

WaitMatch waits until the latest view output matches the regular expression pattern.

See also WaitMatch, Harness.WaitNotMatch, Harness.AssertMatch, and Harness.RequireMatch.

func (*Harness) WaitNotBytes 

func (h *Harness) WaitNotBytes(contents []byte, opts ...Option) *Harness

WaitNotBytes waits until view output contains none of the contents.

See also WaitNotBytes, Harness.WaitBytes, Harness.WaitNotStrings, and Harness.WaitBytesFunc.

func (*Harness) WaitNotMatch 

func (h *Harness) WaitNotMatch(pattern string, opts ...Option) *Harness

WaitNotMatch waits until the latest view output does not match the regular expression pattern.

See also WaitNotMatch, Harness.WaitMatch, Harness.AssertNotMatch, and Harness.RequireNotMatch.

func (*Harness) WaitNotString 

func (h *Harness) WaitNotString(contents string, opts ...Option) *Harness

WaitNotString waits until view output contains none of the contents.

See also WaitNotString, Harness.WaitString, Harness.WaitStrings, and Harness.WaitNotStrings.

func (*Harness) WaitNotStrings 

func (h *Harness) WaitNotStrings(contents []string, opts ...Option) *Harness

WaitNotStrings waits until view output contains none of the contents.

See also WaitNotStrings, Harness.WaitStrings, and Harness.WaitNotString.

func (*Harness) WaitSettle 

func (h *Harness) WaitSettle(opts ...Option) *Harness

WaitSettle waits until the rendered view string from Harness.View has not changed for the configured settle timeout. It polls this harness's Harness.View and compares each result to the previous sample.

See also Harness.WaitSettleMessages, WaitSettle, WithSettle, WithCheck, and WithTimeout.

func (*Harness) WaitSettleMessages 

func (h *Harness) WaitSettleMessages(opts ...Option) *Harness

WaitSettleMessages waits until no messages have been observed for the configured settle timeout.

See also WaitSettleMessages, Harness.WaitSettle, WaitSettle, WithSettle, WithCheck, and WithTimeout.

func (*Harness) WaitString 

func (h *Harness) WaitString(contents string, opts ...Option) *Harness

WaitString waits until view output contains contents.

See also WaitString, Harness.WaitStrings, Harness.WaitNotString, Harness.WaitMatch, and Harness.WaitStringFunc.

func (*Harness) WaitStringFunc 

func (h *Harness) WaitStringFunc(condition func(view string) bool, opts ...Option) *Harness

WaitStringFunc waits until condition returns true for the latest view output. It wraps WaitViewFunc with a string predicate.

See also Harness.WaitBytesFunc, WaitString, WaitNotString, and WaitStrings.

func (*Harness) WaitStrings 

func (h *Harness) WaitStrings(contents []string, opts ...Option) *Harness

WaitStrings waits until view output contains all contents.

See also WaitStrings, Harness.WaitString, and Harness.WaitNotStrings.

func (*Harness) Width 

func (h *Harness) Width() int

Width returns the terminals current width in cells (matches Harness.View output width).

type MessageCollector 

type MessageCollector interface {
	MessageHistory() iter.Seq[uv.Event]
	Messages(ctx context.Context) iter.Seq[uv.Event]
	LiveMessages(ctx context.Context) iter.Seq[uv.Event]
}

MessageCollector exposes messages observed by a test harness. Harness implements this interface.

type Option 

type Option func(*options)

Option configures a Harness or assertion helper. NewHarness and NewComponentHarness store these options and merge them (before per-call options) on any Harness method that accepts more options, so a harness can be configured with defaults once and overridden per call.

func WithANSI 

func WithANSI(enable bool) Option

WithANSI determines whether ANSI sequences should be kept. When false, ANSI sequences are stripped, which will often make it easier to visually and programmatically compare snapshots, output, etc. This would apply to strings/regex comparisons in AssertString, AssertMatch, WaitString, WaitStrings, etc.

func WithCheck 

func WithCheck(interval time.Duration) Option

WithCheck configures how often waits are checked.

See also DefaultCheckInterval.

func WithContext 

func WithContext(ctx context.Context) Option

WithContext sets the parent context for blocking waits (WaitString, WaitMessageWhere, Harness wait helpers, etc.) and for the running tea.Program. Defaults to a notify context through signal.NotifyContext when invoked through Harness, else context.Background.

func WithEnvVars 

func WithEnvVars(vars ...string) Option

WithEnvVars sets extra environment variables for the tea.Program, in the form of "key=value". Defaults:

  • TERM=xterm-256color
  • TERM_PROGRAM=Apple_Terminal

func WithProgramOptions 

func WithProgramOptions(opts ...tea.ProgramOption) Option

WithProgramOptions appends tea.ProgramOption values for NewHarness and NewComponentHarness. The harness always sets environment, context (see WithContext), input and output (via the internal vt emulator), tea.WithoutSignals, and tea.WithWindowSize; those cannot be replaced by options passed here. It has no effect elsewhere.

func WithSettle 

func WithSettle(timeout time.Duration) Option

WithSettle configures how long to wait for the tea.Program to satisfy settle waits. See Harness.WaitSettleMessages, Harness.WaitSettle and WaitSettle for more details.

See also DefaultSettleTimeout.

func WithSettleIgnoreMsgs 

func WithSettleIgnoreMsgs(types ...any) Option

WithSettleIgnoreMsgs marks message types that do not reset the quiet period used by Harness.WaitSettleMessages. Pass a value of each type to ignore (for example a zero value of your periodic tick type). The dynamic type of each observed message is compared with reflect.TypeOf on those samples; nil samples are skipped.

See also [DefaultSettleIgnoreMsgs].

func WithTimeout 

func WithTimeout(timeout time.Duration) Option

WithTimeout configures how long waits may run.

See also DefaultTimeout.

func WithWindowSize 

func WithWindowSize(width, height int) Option

WithWindowSize configures the starting terminal size.

See also DefaultTermWidth and DefaultTermHeight.

type Viewable 

type Viewable func() string

Source Files

View all Source files

Directories

Path Synopsis
internal
broker
Package broker provides a generic in-memory event broker: publishers push events without waiting for slow subscribers; history is optionally retained up to a max size; subscribers receive only events after registration, or may opt into replay of stored history followed by live delivery.
 Package broker provides a generic in-memory event broker: publishers push events without waiting for slow subscribers; history is optionally retained up to a max size; subscribers receive only events after registration, or may opt into replay of stored history followed by live delivery.
vtpipe
Package vtpipe bridges a program's sequential stdin/stdout to blocking reader and writer halves (such as vt.Emulator) using background pumps and buffered I/O.
 Package vtpipe bridges a program's sequential stdin/stdout to blocking reader and writer halves (such as vt.Emulator) using background pumps and buffered I/O.
xansi
Package xansi normalizes terminal output for stable snapshots and assertions: stripping ANSI, spinner glyphs, and private-use code points, normalizing newlines, and escaping ESC for readable diffs.
 Package xansi normalizes terminal output for stable snapshots and assertions: stripping ANSI, spinner glyphs, and private-use code points, normalizing newlines, and escaping ESC for readable diffs.
Package snapshot provides snapshot assertions for tests.
 Package snapshot provides snapshot assertions for tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.