tui

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Feb 3, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CaptureOption 

type CaptureOption func(*captureConfig)

CaptureOption configures capture behavior

func WithCleanedOutput 

func WithCleanedOutput() CaptureOption

WithCleanedOutput is a capture option to get pane content with ANSI codes stripped.

func WithRawOutput 

func WithRawOutput() CaptureOption

WithRawOutput is a capture option to get the raw pane content with ANSI codes.

type RecordedEvent 

type RecordedEvent struct {
	Timestamp time.Time   `json:"timestamp"`
	Type      string      `json:"type"` // "key", "capture", "assert", "wait", "navigate"
	Data      interface{} `json:"data"`
	Result    string      `json:"result,omitempty"`
	Error     string      `json:"error,omitempty"`
}

RecordedEvent represents a single action or assertion in the session.

type ScreenCapture 

type ScreenCapture struct {
	Timestamp time.Time `json:"timestamp"`
	Content   string    `json:"content"`
	Raw       string    `json:"raw,omitempty"`
}

ScreenCapture represents a snapshot of the TUI at a point in time.

type Session 

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

Session represents an active TUI application running in a tmux session. It provides a high-level API for interaction and assertion.

func NewSession 

func NewSession(sessionName string, client *tmux.Client, rootDir string) *Session

NewSession creates a new TUI session handle. It is intended for internal use by the harness.

func (*Session) AssertContains 

func (s *Session) AssertContains(text string) error

AssertContains immediately checks if the TUI's current content contains the specified text. NOTE: For better test reporting, it is recommended to use this with the harness context: 

err := ctx.Check("should show welcome message", session.AssertContains("Welcome"))

func (*Session) AssertContainsPattern 

func (s *Session) AssertContainsPattern(pattern *regexp.Regexp) error

AssertContainsPattern checks if the current screen content matches the regex pattern.

func (*Session) AssertFileContains 

func (s *Session) AssertFileContains(relPath string, content string) error

AssertFileContains asserts that a file within the scenario's temporary directory contains specific content.

func (*Session) AssertFileExists 

func (s *Session) AssertFileExists(relPath string) error

AssertFileExists asserts that a file exists within the scenario's temporary directory.

func (*Session) AssertLine 

func (s *Session) AssertLine(predicate func(line string) bool, message string) error

AssertLine iterates through each visible line of the TUI and passes if the predicate function returns true for any line. This is a flexible way to assert complex states like focus or selection without relying on specific ANSI codes.

func (*Session) AssertNotContains 

func (s *Session) AssertNotContains(text string) error

AssertNotContains immediately checks if the TUI's current content does not contain the specified text. NOTE: For better test reporting, it is recommended to use this with the harness context: 

err := ctx.Check("should not show error", session.AssertNotContains("Error:"))

func (*Session) Capture 

func (s *Session) Capture(opts ...CaptureOption) (string, error)

Capture returns the visible text content of the TUI pane. By default, it returns raw content with ANSI escape codes.

func (*Session) Close 

func (s *Session) Close() error

Close terminates the tmux session associated with the TUI. This is typically called automatically by the test harness on cleanup.

func (*Session) FindTextLocation 

func (s *Session) FindTextLocation(text string) (row, col int, found bool, err error)

FindTextLocation searches the screen for the given text and returns its 1-based (row, col) position if found.

func (*Session) GetCursorPosition 

func (s *Session) GetCursorPosition() (row, col int, err error)

GetCursorPosition returns the 1-based (row, col) of the cursor.

func (*Session) GetKeyHistory 

func (s *Session) GetKeyHistory() []string

GetKeyHistory returns all keys sent during the session.

func (*Session) GetVisibleLines 

func (s *Session) GetVisibleLines() ([]string, error)

GetVisibleLines returns the current screen content as a slice of lines.

func (*Session) NavigateToText 

func (s *Session) NavigateToText(text string) error

NavigateToText moves the selection to the line containing the specified text. For selection-based TUIs (like lists), it finds lines with selection indicators (">", "*", "•") and calculates navigation from the current selection. For cursor-based interfaces, it uses tmux cursor position. Waits for UI to stabilize after each keypress.

func (*Session) SaveRecording 

func (s *Session) SaveRecording() error

SaveRecording exports the session data to multiple formats.

func (*Session) SelectItem 

func (s *Session) SelectItem(predicate func(line string) bool) error

SelectItem navigates to and selects an item matching the predicate. It searches visible lines and moves the cursor to the first match, then presses Enter.

func (*Session) SelectItemWithKey 

func (s *Session) SelectItemWithKey(predicate func(line string) bool, key string) error

SelectItemWithKey navigates to an item matching the predicate and presses the specified key.

func (*Session) SendKeys 

func (s *Session) SendKeys(keys ...string) error

SendKeys sends a sequence of keystrokes to the TUI without waiting. Special keys can be sent (e.g., "Enter", "Esc", "Ctrl+c").

NOTE: In most cases, you should use Type() instead, which automatically waits for the screen to stabilize after sending keys.

func (*Session) SendKeysAndWaitForChange 

func (s *Session) SendKeysAndWaitForChange(timeout time.Duration, keys ...string) error

SendKeysAndWaitForChange sends keys and waits for the screen to change.

func (*Session) StartRecording 

func (s *Session) StartRecording(outputPath string) error

StartRecording begins recording the session to the specified output path.

func (*Session) StopRecording 

func (s *Session) StopRecording() error

StopRecording stops recording and saves the session data.

func (*Session) TakeScreenshot 

func (s *Session) TakeScreenshot(filepath string) error

TakeScreenshot captures the current TUI state to a file.

func (*Session) Type 

func (s *Session) Type(keys ...string) error

Type sends keys to the TUI and waits for the screen to stabilize. This is the recommended method for most interactions, as it combines SendKeys + WaitStable which is the pattern used in 90% of tests.

Special handling for vim-style chord commands: When multiple identical single-character keys are passed (like "g", "g"), they are sent individually with stabilization between each key. This ensures vim chord commands like "gg" are properly recognized.

Example: 

session.Type("j")           // Navigate down and wait
session.Type("g", "g")      // Go to top (sends separately for chord recognition)
session.Type("/", "search") // Open search and type

func (*Session) WaitForAnyText 

func (s *Session) WaitForAnyText(texts []string, timeout time.Duration) (string, error)

WaitForAnyText waits for any of the specified texts to appear on screen. Returns the first matching text found, or an error if timeout is reached.

func (*Session) WaitForFile 

func (s *Session) WaitForFile(relPath string, timeout time.Duration) error

WaitForFile waits for a file to exist within the scenario's temporary directory.

func (*Session) WaitForText 

func (s *Session) WaitForText(text string, timeout time.Duration) error

WaitForText polls the TUI's content until the specified text appears or the timeout is reached.

func (*Session) WaitForTextPattern 

func (s *Session) WaitForTextPattern(pattern *regexp.Regexp, timeout time.Duration) (string, error)

WaitForTextPattern waits for text matching the regex pattern to appear. Returns the matched text, or an error if timeout is reached.

func (*Session) WaitForUIStable 

func (s *Session) WaitForUIStable(timeout time.Duration, pollInterval time.Duration, stableDuration time.Duration) error

WaitForUIStable polls the TUI screen until its content remains unchanged for the specified stable duration, or until the timeout is reached. This is useful for waiting for animations or asynchronous updates to complete.

Parameters: - timeout: Maximum time to wait for stability (e.g., 10*time.Second) - pollInterval: How often to check the screen (e.g., 100*time.Millisecond) - stableDuration: How long the screen must be unchanged to be considered stable (e.g., 200*time.Millisecond)

For most use cases, use WaitStable() instead, which provides sensible defaults.

func (*Session) WaitStable 

func (s *Session) WaitStable() error

WaitStable waits for the UI to stabilize using sensible defaults. This is equivalent to WaitForUIStable(10*time.Second, 100*time.Millisecond, 200*time.Millisecond).

The 10 second timeout accommodates slow CI environments but returns immediately once the UI stabilizes (typically 300-500ms for test fixtures).

Use this method for most testing scenarios. Use WaitForUIStable() directly only if you need custom timing parameters.

type SessionRecording 

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

SessionRecording tracks all events and captures during a TUI session.

type StartConfig 

type StartConfig struct {
	Env []string
	Cwd string
}

StartConfig holds configuration for launching a TUI session.

type StartOption 

type StartOption func(*StartConfig)

StartOption is a function that configures a StartConfig.

func WithCwd 

func WithCwd(cwd string) StartOption

WithCwd sets the working directory for the TUI session.

func WithEnv 

func WithEnv(env ...string) StartOption

WithEnv sets environment variables for the TUI session. Variables should be in KEY=VALUE format.

Source Files

View all Source files

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.