#snapshot #terminal #svg

term-transcript

Snapshotting and snapshot testing for CLI / REPL applications

1 unstable release

0.1.0 Jun 1, 2021

#164 in Testing


Used in term-transcript-cli

MIT/Apache

135KB
3K SLoC

Snapshot Testing for CLI / REPL Applications

Build Status License: MIT OR Apache-2.0 rust 1.45.0+ required

Documentation: crate docs (master)

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
  • 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.

Usage

Add this to your Crate.toml:

[dependencies]
term-transcript = "0.1.0"

Example of usage:

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

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)?);
Ok::<_, anyhow::Error>(())

See more examples in the crate docs.

Snapshot examples

Here's an SVG snapshot of the rainbow example produced by this crate:

Snapshot of rainbow example

Here's a snapshot of the same example with the scrolling animation and window frame:

Animated snapshot of rainbow example

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 an error.
  • 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 on isatty 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.
  • 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).
  • 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.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in term-transcript by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~0.3–1MB
~19K SLoC