Documentation
¶
Overview ¶
Package testterm provides an ANSI-interpreting virtual terminal for testing terminal output, plus a scripted session for driving interactive code.
A Term is an io.Writer: hand it to the code under test in place of the real connection, then assert on the resulting screen with Row, Cell, Cursor and Snapshot instead of on raw escape sequences.
Term is not a terminal emulator. It models the subset of ANSI that internal/editor emits and records everything else in Unhandled, so a test can catch output the double does not understand rather than silently passing.
One piece of the BBS relies on it outside tests: toast delivery in internal/menu replays a session's screen through a Term to redraw the one row an overlay covered, and falls back to replaying the whole screen when Unhandled is not empty. Anything added to the model must therefore be right, not merely good enough for an assertion.
Index ¶
- type Cell
- type Option
- type Session
- type Term
- func (t *Term) Cell(row, col int) Cell
- func (t *Term) Cursor() (row, col int)
- func (t *Term) CursorVisible() bool
- func (t *Term) Doubts() []string
- func (t *Term) Pen() Cell
- func (t *Term) Row(row int) string
- func (t *Term) RowCells(row int) []Cell
- func (t *Term) Snapshot() string
- func (t *Term) Unhandled() []string
- func (t *Term) Write(p []byte) (int, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cell ¶
Cell is one character position on the screen.
Fg and Bg hold the SGR parameter as written (30-37 and 90-97 for foreground, 40-47 and 100-107 for background); -1 means the terminal default.
type Session ¶
type Session struct {
ssh.Session // nil; supplies the rest of the interface
// contains filtered or unexported fields
}
Session is a scripted ssh.Session for driving interactive terminal code. Read replays the keystrokes it was given; Write forwards to a Term so one object covers both directions of a test.
Once the scripted input is exhausted, Read blocks until the read interrupt fires if one is set, and returns io.EOF otherwise. That mirrors the ssh and telnet adapters: a live connection does not report EOF just because the user has stopped typing, and code that relies on a read returning is what leaks goroutines when it is wrong.
Session embeds a nil ssh.Session only to satisfy the rest of the interface; Read, Write and Pty are implemented here, but any other promoted method (Environ, Command, Exit, ...) panics on the nil receiver if called.
func NewSession ¶
NewSession creates a session that replays keys and renders output to term. term may be nil, in which case output is discarded.
func (*Session) Pty ¶
Pty reports that the session has no PTY. Session does not model PTY negotiation; RunEditorWithMetadata and similar callers treat a false isPty as "use default dimensions", which is what tests driving a Session want.
func (*Session) Read ¶
Read replays scripted input. See the type comment for exhausted-input behaviour.
When input is exhausted and an interrupt is set, Read also watches for a Send: Send is how a test feeds keys in stages to code running concurrently on another goroutine, which only makes sense if a Read blocked waiting for those keys actually wakes up when they arrive. Send's non-blocking signal on s.sent is buffered (capacity 1), so a Send landing between the buffer check below and the select is not lost — it is sitting in the channel ready for the select to consume immediately.
func (*Session) Send ¶
Send appends more input, for tests that feed keys in stages. It wakes a Read that is already blocked waiting for the interrupt, so keys fed after Read has been called are delivered instead of sitting unseen until the interrupt fires.
func (*Session) SetReadInterrupt ¶
func (s *Session) SetReadInterrupt(ch <-chan struct{})
SetReadInterrupt installs the channel that unblocks a pending Read.
type Term ¶
type Term struct {
// contains filtered or unexported fields
}
Term is a virtual screen that records what was drawn on it.
Term is safe for concurrent use: Write and every accessor take an internal mutex. That matters when a test drives interactive code through a Session — the code under test writes to the Term on its own goroutine while the test goroutine reads Row, Cell, Cursor or Snapshot to make assertions.
func New ¶
New creates a Term of the given size with an empty screen and the cursor at row 1, column 1.
func (*Term) Cell ¶
Cell returns the cell at a 1-based row and column. Out-of-range coordinates return a blank cell so that a mistaken assertion fails rather than panics.
func (*Term) Cursor ¶
Cursor returns the 1-based cursor position. After a write that lands exactly on the last column, the column stays at width — never past it — while the wrap to the next row is deferred until the next character arrives (see putRune's wrapPending flag), matching real terminal behaviour.
func (*Term) CursorVisible ¶
CursorVisible reports whether the cursor is shown (ESC[?25h / ESC[?25l).
func (*Term) Doubts ¶ added in v0.9.7
Doubts returns the operations this Term carried out whose effect on a real terminal it may have got wrong: a scroll, which some terminals fill with the pen's background and this Term fills with the default, and a character the Term gave one cell though a UTF-8 terminal may give it two or none. They are not in Unhandled, since tests legitimately exercise both; code that reads the screen back from a Term, as the toast restore does, must check them.
func (*Term) Pen ¶ added in v0.9.7
Pen returns the current SGR state: what the next character written would be drawn with. Its Rune is unused.
func (*Term) Row ¶
Row returns the text of a 1-based row with trailing blanks removed. An out-of-range row returns "".
func (*Term) RowCells ¶ added in v0.9.7
RowCells returns a copy of a 1-based row's cells, attributes included. An out-of-range row returns nil.
func (*Term) Snapshot ¶
Snapshot returns the whole screen as text: rows joined by "\n", with trailing blanks on each row and trailing blank rows removed. Colour is deliberately excluded — assert colour through Cell.
func (*Term) Unhandled ¶
Unhandled returns the escape sequences this Term consumed but did not model, in the order they arrived, plus a trailing entry when the stream ended mid-sequence (bytes are still sitting in the pending buffer, waiting for a Write that never came). A test that wants to be sure the double kept up with the code under test asserts this is empty.
func (*Term) Write ¶
Write feeds terminal output to the screen. It never returns an error; the io.Writer signature is what the code under test expects.
Bytes held back mid-sequence or mid-rune are carried over to the next call, so a sequence split across writes is still parsed as one sequence.
Write takes Term's mutex for the whole call, so a Write racing with an accessor on another goroutine (the shape a Session-driven test uses) is safe.