Enum Error 

#[non_exhaustive]
pub enum Error {
    Timeout {
        waiting_for: String,
        timeout: Duration,
        screen: Screen,
    },
    Eof {
        waiting_for: String,
        screen: Screen,
    },
    Spawn {
        command: String,
        reason: String,
    },
    Pty(String),
    Io(Error),
    Size(String),
    Emulator {
        detail: String,
        screen: Screen,
    },
    Input(String),
    Parse(String),
    Write {
        what: Box<str>,
        screen: Screen,
    },
}

Errors returned by Terminal operations.

TERMLENS_ARTIFACT_DIR

Every variant that carries a Screen prints it, so a CI log shows what the application displayed. When the environment variable TERMLENS_ARTIFACT_DIR names a directory, the same screen is also written there as it is embedded: <test>-<n>.screen.json with the serde feature, <test>-<n>.screen.txt (the with_styles rendering, which Screen::parse reads back) without, where <test> is the current thread’s name — under cargo test, the test’s path. Unset, the hook is one environment read and nothing else; insta’s .snap.new files stay where insta puts them. This repository’s report action (.github/actions/report) renders that directory into a pull request’s step summary.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Timeout

A wait_* call ran past its deadline. The screen at the moment of the timeout is embedded and printed, so a CI log alone is enough to see what the application was actually showing.

Fields

waiting_for: String

Human description of what was awaited.

timeout: Duration

The deadline that expired.

screen: Screen

The screen when the deadline expired.

Eof

The PTY reached end-of-file (the child exited or closed its terminal) while a wait’s condition was still unmet. Waiting longer can never succeed, so this fails fast instead of burning the full timeout.

Fields

waiting_for: String

Human description of what was awaited.

screen: Screen

The final screen contents.

Spawn

Spawning the child process failed.

Fields

command: String

The command line that failed to spawn.

reason: String

The underlying PTY/OS error.

Pty(String)

A PTY control operation (open, resize, reader/writer setup) failed.

Io(Error)

An OS-level I/O error (e.g. while waiting on the child process).

Size(String)

A terminal size argument is invalid and was rejected before anything was spawned or sent to the child.

Emulator

The VT emulator panicked while processing the child’s output, so the grid stopped advancing at the screen embedded here.

The emulation runs on the reader thread, where a panic propagates nowhere: before this existed the drain simply died, every later snapshot returned the same frozen screen, and each wait ran to its deadline reporting a predicate that was never going to become true. A wait now fails immediately and says why. The screen is the last one taken before the failure — the emulator is not asked again, because its state after a panic means nothing.

Fields

detail: String

The panic message from the emulator.

screen: Screen

The last screen taken before the emulator failed.

Input(String)

Typed input or control the child cannot receive — e.g. a mouse click while the application never enabled mouse tracking (sending it anyway would feed the app bytes it would misparse as garbage keys), or a signal to a child that has already been reaped (its pid may belong to someone else by now).

Parse(String)

A saved screen could not be read back by Screen::parse: the text is not the snapshot format of docs/DESIGN.md §3. The message names the line.

Write

Typed input could not be delivered: the child is gone and the OS tore the terminal down, or it stopped reading its input and the write gave up at the terminal’s deadline rather than blocking forever.

Distinct from Error::Input on purpose. Input means the application cannot make sense of these bytes — a test bug. This means the bytes could not be handed over at all, which is a fact about the child rather than about the test, so the screen at the moment of the failure is embedded the way a timeout’s is.

Fields

what: Box<str>

What was being sent, which command it was going to, and why the write failed.

screen: Screen

The screen when the write failed.

Implementations

impl Error

pub fn screen(&self) -> Option<&Screen>

The screen embedded in Error::Timeout, Error::Eof, Error::Emulator or Error::Write, if any.

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.