Snapshot Testing for CLI / REPL Applications

Documentation:

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. Rendering logic can be customized via [Handlebars] template engine; thus, other output formats besides SVG (e.g., HTML) are possible. See crate docs for an intro to custom 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.

Usage

Add this to your Crate.toml:

toml [dependencies] term-transcript = "0.3.0"

Example of usage:

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

let transcript = Transcript::frominputs( &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::fromutf8(&writer)?); Ok::<_, anyhow::Error>(()) ```

See more examples in the crate docs and the FAQ for some tips and troubleshooting advice.

CLI app

Most of the library functionality is packaged into a CLI binary, which allows using the library without Rust knowledge. See the binary docs for the installation and usage guides.

Snapshot examples

An SVG snapshot of the rainbow example produced by this crate:

A snapshot of the same example with the scrolling animation and window frame:

A snapshot of a similar example rendered to HTML using a custom template is available as a source file and in the rendered form.

See the examples directory for more snapshot examples.

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.
• 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).
• PTY support for Windows is shaky. It requires a somewhat recent Windows version (Windows 10 from October 2018 or newer), and may work incorrectly even for the recent versions.

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.

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.