Crate term_transcript

Snapshot testing for CLI / REPL applications, in a fun way.

What it does

This crate allows to:

• Create Transcripts of interacting with a terminal, capturing both the output text and ANSI-compatible color info.
• Save these transcripts in the SVG format, so that they can be easily embedded as images into HTML / Markdown documents. (Output format customization is also supported via Handlebars templates.)
• Parse transcripts from SVG
• Test that a parsed transcript actually corresponds to the terminal output (either as text or text + colors).

The primary use case is easy to create and maintain end-to-end tests for CLI / REPL apps. Such tests can be embedded into a readme file.

Design decisions

• Static capturing. Capturing dynamic interaction with the terminal essentially requires writing / hacking together a new terminal, which looks like an overkill for the motivating use case (snapshot testing).

• (Primarily) static SVGs. Animated SVGs create visual noise and make simple things (e.g., copying text from an SVG) harder than they should be.

• Self-contained tests. Unlike generic snapshot files, Transcripts contain both user inputs and outputs. This allows using them as images with little additional explanation.

Limitations

• Terminal coloring only works with ANSI escape codes. (Since ANSI escape codes are supported even on Windows nowadays, this shouldn’t be a significant problem.)
• ANSI escape sequences other than SGR ones are either dropped (in case of CSI and OSC sequences), or lead to TermError::UnrecognizedSequence.
• By default, the crate exposes APIs to perform capture via OS pipes. Since the terminal is not emulated in this case, programs dependent on isatty checks or getting term size can produce different output than if launched in an actual shell (no coloring, no line wrapping etc.).
• It is possible to capture output from a pseudo-terminal (PTY) using the portable-pty crate feature. However, since most escape sequences are dropped, this is still not a good option to capture complex outputs (e.g., ones moving cursor).

Alternatives / similar tools

• insta is a generic snapshot testing library, which is amazing in general, but kind of too low-level for E2E CLI testing.
• rexpect allows testing CLI / REPL applications by scripting interactions with them in tests. It works in Unix only.
• trybuild snapshot-tests output of a particular program (the Rust compiler).
• trycmd snapshot-tests CLI apps using a text-based format.
• Tools like termtosvg and Asciinema allow recording terminal sessions and save them to SVG. The output of these tools is inherently dynamic (which, e.g., results in animated SVGs). This crate intentionally chooses a simpler static format, which makes snapshot testing easier.

Crate features

portable-pty

(Off by default)

Allows using pseudo-terminal (PTY) to capture terminal output rather than pipes. Uses the eponymous crate under the hood.

svg

(On by default)

Exposes the eponymous module that allows rendering Transcripts into the SVG format.

test

(On by default)

Exposes the eponymous module that allows parsing Transcripts from SVG files and testing them.

pretty_assertions

(On by default)

Uses the eponymous crate when testing SVG files. Only really makes sense together with the test feature.

tracing

(Off by default)

Uses the eponymous facade to trace main operations, which could be useful for debugging. Tracing is mostly performed on the DEBUG level.

Examples

Creating a terminal Transcript and rendering it to SVG.

use term_transcript::{
    svg::{Template, TemplateOptions}, ShellOptions, Transcript, UserInput,
};

let transcript = Transcript::from_inputs(
    &mut ShellOptions::default(),
    vec![UserInput::command(r#"echo "Hello world!""#)],
)?;
let mut writer = vec![];
// ^ Any `std::io::Write` implementation will do, such as a `File`.
Template::new(TemplateOptions::default()).render(&transcript, &mut writer)?;
println!("{}", str::from_utf8(&writer)?);

Snapshot testing. See the test module for more examples.

use term_transcript::{test::TestConfig, ShellOptions};

#[test]
fn echo_works() {
    TestConfig::new(ShellOptions::default()).test(
        "tests/__snapshots__/echo.svg",
        &[r#"echo "Hello world!""#],
    );
}

Modules

• svgsvg
  Provides templating logic for rendering terminal output in a visual format.
• testtest
  Snapshot testing tools for Transcripts.
• traits
  Traits for interaction with the terminal.

Structs

• Captured
  Output captured from the terminal.
• ExitStatus
  Portable, platform-independent version of ExitStatus from the standard library.
• Interaction
  One-time interaction with the terminal.
• PtyCommand
  Command to spawn in a pseudo-terminal (PTY).
• PtyShell
  Spawned shell process connected to pseudo-terminal (PTY).
• ShellOptions
  Options for executing commands in the shell. Used in Transcript::from_inputs() and in TestConfig.
• StdShell
  Shell interpreter that brings additional functionality for ShellOptions.
• Transcript
  Transcript of a user interacting with the terminal.
• UserInput
  User input during interaction with a terminal.

Enums

• TermError
  Errors that can occur when processing terminal output.

Traits

• TermOutput
  Marker trait for supported types of terminal output.