Documentation
¶
Overview ¶
Package ptytest provides a PTY-based test harness for interactive terminal testing. It spawns commands in a pseudo-terminal and provides event-driven Send/WaitFor primitives.
Index ¶
- Constants
- func LogProcessTree(t *testing.T, label string, rootPID int)
- func ProcessRawOutput(raw string) string
- func SanitizeOutput(s string) string
- func StripANSI(s string) string
- type Console
- func (c *Console) Close(t *testing.T)
- func (c *Console) CmdPath() string
- func (c *Console) DiscardLastSnapshot()
- func (c *Console) Env(key string) (string, bool)
- func (c *Console) LauncherPid() int
- func (c *Console) Output() string
- func (c *Console) Pid() int
- func (c *Console) RawOutput() string
- func (c *Console) RequireExitCode(t *testing.T, expectedExitCode int)
- func (c *Console) RequireSuccessfulExit(t *testing.T)
- func (c *Console) ResetSnapshots()
- func (c *Console) RewriteLastSnapshot(rewrite func(string) string)
- func (c *Console) Send(t *testing.T, s string)
- func (c *Console) SendKey(t *testing.T, key byte)
- func (c *Console) SendLine(t *testing.T, s string)
- func (c *Console) Signal(t *testing.T, sig os.Signal)
- func (c *Console) Snapshots() []string
- func (c *Console) WaitFor(t *testing.T, pattern string) string
- func (c *Console) WaitForExit(t *testing.T) error
- func (c *Console) WaitForTimeout(t *testing.T, pattern string, timeout time.Duration) string
- type Option
Constants ¶
const ( KeyEnter = '\r' KeyEscape = '\x1b' KeyBackspace = '\x7f' KeyCtrlC = '\x03' KeyCtrlD = '\x04' )
Predefined key constants for SendKey.
Variables ¶
This section is empty.
Functions ¶
func LogProcessTree ¶
LogProcessTree logs the process tree rooted at rootPID to the test log. label is a descriptive name used to identify the tree in the log. This is a standalone diagnostic helper, not tied to any Console, useful for diagnosing external processes (e.g. sshd) that may be hanging when a test fails.
func ProcessRawOutput ¶
ProcessRawOutput processes raw terminal output through a minimal terminal emulator, properly handling cursor movement and screen clearing sequences that bubbletea uses for in-place rendering.
Unlike simple ANSI stripping (which loses cursor movement semantics and produces non-deterministic output depending on render batching), this function resolves cursor-up, clear-to-end, and other positioning sequences to produce the text that would actually be visible on a terminal screen.
The resulting output is deterministic because regardless of how many intermediate renders bubbletea performed, the final screen state is the same.
func SanitizeOutput ¶
SanitizeOutput provides basic output sanitization compatible with the existing golden file format: strips ANSI, removes trailing whitespace from lines, and normalizes line endings.
Types ¶
type Console ¶
type Console struct {
// contains filtered or unexported fields
}
Console represents a running command in a PTY.
func Start ¶
Start spawns the command in a PTY and returns a Console. The command is automatically terminated and the PTY cleaned up when the test ends.
func (*Console) Close ¶
Close terminates the command (if still running) and cleans up the PTY. It is safe to call multiple times. It is also called automatically on test cleanup.
func (*Console) DiscardLastSnapshot ¶
func (c *Console) DiscardLastSnapshot()
DiscardLastSnapshot removes the most recently captured snapshot. Useful when a WaitFor call captures a timing-sensitive intermediate state that should not appear in the golden file.
func (*Console) Env ¶
Env returns the value of an environment variable passed to the spawned command.
func (*Console) LauncherPid ¶
LauncherPid returns the PID of the launcher command.
func (*Console) Output ¶
Output returns all terminal output captured so far, with ANSI escape sequences stripped.
func (*Console) RawOutput ¶
RawOutput returns all terminal output captured so far, including ANSI escape sequences.
func (*Console) RequireExitCode ¶
RequireExitCode waits for command exit and requires the expected non-zero exit code.
func (*Console) RequireSuccessfulExit ¶
RequireSuccessfulExit waits for command exit and requires exit code 0.
func (*Console) ResetSnapshots ¶
func (c *Console) ResetSnapshots()
ResetSnapshots discards all snapshots captured so far. Useful to ignore preliminary interaction steps (e.g. waiting for a prompt before the meaningful flow begins) when WithSnapshots is enabled.
func (*Console) RewriteLastSnapshot ¶
RewriteLastSnapshot rewrites the most recently captured snapshot in place. If no snapshots were captured yet, it does nothing.
func (*Console) Snapshots ¶
Snapshots returns the terminal screen states captured at each WaitFor match point and after WaitForExit. Consecutive duplicate snapshots are removed. Only populated when WithSnapshots() option was used.
func (*Console) WaitFor ¶
WaitFor blocks until the accumulated terminal output (from the current scan position) matches the given regexp pattern, or the default timeout expires. On timeout, the test is failed with diagnostic output. Returns the matched output.
func (*Console) WaitForExit ¶
WaitForExit blocks until the command exits and all PTY output has been drained. Returns the exit error (nil on success).
type Option ¶
type Option func(*options)
Option configures a PTY test session.
func WithSnapshots ¶
func WithSnapshots() Option
WithSnapshots enables automatic terminal screen snapshot capture after each successful WaitFor call. Use Snapshots() to retrieve the captured states. This is useful for TUI applications that redraw in-place (e.g. bubbletea), where the final terminal state alone loses intermediate interaction steps.
func WithTimeout ¶
WithTimeout sets the default timeout for WaitFor operations.
Source Files
Directories