7 unstable releases
0.4.0-beta.1 | Mar 3, 2024 |
---|---|
0.3.0 | Jun 3, 2023 |
0.3.0-beta.2 | Apr 29, 2023 |
0.3.0-beta.1 | Jan 19, 2023 |
0.1.0 | Jun 1, 2021 |
#92 in Testing
1,131 downloads per month
Used in 4 crates
330KB
7.5K
SLoC
Capturing and Snapshot Testing for CLI / REPL Applications
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
:
[dependencies]
term-transcript = "0.4.0-beta.1"
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 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:
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.
Dependencies
~1.4–9.5MB
~86K SLoC