Crate term_transcript[−][src]
Expand description
Snapshot testing for CLI / REPL applications, in a fun way.
What it does
This crate allows to:
- Create
Transcript
s 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
- 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,
Transcript
s 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 sequences),
or lead to
TermError::NonCsiSequence
. - Pseudo-terminal (PTY) APIs are not used in order to be more portable. This can change in the future releases.
- Since the terminal is not emulated, programs dependent on
isatty
checks can produce different output than if launched in an actual shell. One can argue that dependence onisatty
is generally an anti-pattern. - As a consequence of the last point, CLI tools frequently switch off output coloring if not
writing to a terminal. For some tools, this can be amended by adding an arg to the command,
such as
--color=always
.
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.trybuild
snapshot-tests output of a particular program (the Rust compiler).- 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
svg
. Exposes the eponymous module that allows renderingTranscript
s into the SVG format.test
. Exposes the eponymous module that allows parsingTranscript
s from SVG files and testing them.pretty_assertions
. Uses the eponymous crate when testing SVG files. Only really makes sense together with thetest
feature.
svg
, test
and pretty_assertions
features are on by default.
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)?);
Loading a Transcript
and testing it. See the test
module for more examples.
use term_transcript::{test::TestConfig, ShellOptions, Transcript, UserInput}; use std::io; fn read_svg_file() -> anyhow::Result<impl io::BufRead> { // snipped... } let reader = read_svg_file()?; let transcript = Transcript::from_svg(reader)?; TestConfig::new(ShellOptions::default()).test_transcript(&transcript);
Modules
svg | svg Provides the SVG template for rendering terminal output in a visual format. |
test | test Snapshot testing tools for |
Structs
Captured | Output captured from the terminal. |
Interaction | One-time interaction with the terminal. |
ShellOptions | Options for executing commands in the shell. Used in |
Transcript | Transcript of a user interacting with the terminal. |
UserInput | User input during interaction with a terminal. |
Enums
StdShell | Shell interpreter that brings additional functionality for |
TermError | Errors that can occur when processing terminal output. |
Traits
TermOutput | Marker trait for supported types of terminal output. |