1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
//! 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][SGR].
//! - 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]
//! 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`](https://crates.io/crates/insta) is a generic snapshot testing library, which
//! is amazing in general, but *kind of* too low-level for E2E CLI testing.
//! - [`trybuild`](https://crates.io/crates/trybuild) snapshot-tests output
//! of a particular program (the Rust compiler).
//! - Tools like [`termtosvg`](https://github.com/nbedos/termtosvg) and
//! [Asciinema](https://asciinema.org/) 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](#design-decisions) a simpler static format, which
//! makes snapshot testing easier.
//!
//! [SVG]: https://developer.mozilla.org/en-US/docs/Web/SVG
//! [SGR]: https://en.wikipedia.org/wiki/ANSI_escape_code#SGR
//! [CSI]: https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences
//! [`isatty`]: https://man7.org/linux/man-pages/man3/isatty.3.html
//!
//! # Crate features
//!
//! - `portable-pty`. Allows using pseudo-terminal (PTY) to capture terminal output rather
//! than pipes. Uses [the eponymous crate][`portable-pty`] under the hood.
//! - `svg`. Exposes [the eponymous module](crate::svg) that allows rendering [`Transcript`]s
//! into the SVG format.
//! - `test`. Exposes [the eponymous module](crate::test) that allows parsing [`Transcript`]s
//! from SVG files and testing them.
//! - `pretty_assertions`. Uses [the eponymous crate][`pretty_assertions`] when testing SVG files.
//! Only really makes sense together with the `test` feature.
//!
//! `svg`, `test` and `pretty_assertions` features are on by default.
//!
//! [`pretty_assertions`]: https://docs.rs/pretty_assertions/
//! [`portable-pty`]: https://docs.rs/portable-pty/
//!
//! # Examples
//!
//! Creating a terminal [`Transcript`] and rendering it to SVG.
//!
//! ```
//! use term_transcript::{
//! svg::{Template, TemplateOptions}, ShellOptions, Transcript, UserInput,
//! };
//! # use std::str;
//!
//! # fn main() -> anyhow::Result<()> {
//! 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(())
//! # }
//! ```
//!
//! Snapshot testing. See the [`test` module](crate::test) 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!""#],
//! );
//! }
//! ```
// Documentation settings.
#![doc(html_root_url = "https://docs.rs/term-transcript/0.2.0-beta.1")]
#![cfg_attr(docsrs, feature(doc_cfg))]
// Linter settings.
#![warn(missing_debug_implementations, missing_docs, bare_trait_objects)]
#![warn(clippy::all, clippy::pedantic)]
#![allow(clippy::must_use_candidate, clippy::module_name_repetitions)]
use std::{borrow::Cow, error::Error as StdError, fmt, io, num::ParseIntError};
mod html;
#[cfg(feature = "portable-pty")]
mod pty;
mod shell;
#[cfg(feature = "svg")]
#[cfg_attr(docsrs, doc(cfg(feature = "svg")))]
pub mod svg;
mod term;
#[cfg(feature = "test")]
#[cfg_attr(docsrs, doc(cfg(feature = "test")))]
pub mod test;
pub mod traits;
mod utils;
#[cfg(feature = "portable-pty")]
pub use self::pty::{PtyCommand, PtyShell};
pub use self::{
shell::{ShellOptions, StdShell},
term::{Captured, TermOutput},
};
/// Errors that can occur when processing terminal output.
#[derive(Debug)]
#[non_exhaustive]
pub enum TermError {
/// Unfinished escape sequence.
UnfinishedSequence,
/// Unrecognized escape sequence (not a CSI or OSC one). The enclosed byte
/// is the first byte of the sequence (excluding `0x1b`).
UnrecognizedSequence(u8),
/// Invalid final byte for an SGR escape sequence.
InvalidSgrFinalByte(u8),
/// Unfinished color spec.
UnfinishedColor,
/// Invalid type of a color spec.
InvalidColorType(String),
/// Invalid ANSI color index.
InvalidColorIndex(ParseIntError),
/// IO error.
Io(io::Error),
}
impl fmt::Display for TermError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::UnfinishedSequence => formatter.write_str("Unfinished ANSI escape sequence"),
Self::UnrecognizedSequence(byte) => {
write!(
formatter,
"Unrecognized escape sequence (first byte is {})",
byte
)
}
Self::InvalidSgrFinalByte(byte) => {
write!(
formatter,
"Invalid final byte for an SGR escape sequence: {}",
byte
)
}
Self::UnfinishedColor => formatter.write_str("Unfinished color spec"),
Self::InvalidColorType(ty) => {
write!(formatter, "Invalid type of a color spec: {}", ty)
}
Self::InvalidColorIndex(err) => {
write!(formatter, "Failed parsing color index: {}", err)
}
Self::Io(err) => write!(formatter, "I/O error: {}", err),
}
}
}
impl StdError for TermError {
fn source(&self) -> Option<&(dyn StdError + 'static)> {
match self {
Self::InvalidColorIndex(err) => Some(err),
Self::Io(err) => Some(err),
_ => None,
}
}
}
/// Transcript of a user interacting with the terminal.
#[derive(Debug, Clone)]
pub struct Transcript<Out: TermOutput = Captured> {
interactions: Vec<Interaction<Out>>,
}
impl<Out: TermOutput> Default for Transcript<Out> {
fn default() -> Self {
Self {
interactions: vec![],
}
}
}
impl<Out: TermOutput> Transcript<Out> {
/// Creates an empty transcript.
pub fn new() -> Self {
Self::default()
}
/// Returns interactions in this transcript.
pub fn interactions(&self) -> &[Interaction<Out>] {
&self.interactions
}
}
impl Transcript {
/// Adds a new interaction into the transcript.
pub fn add_interaction(&mut self, input: UserInput, output: impl Into<String>) -> &mut Self {
self.interactions.push(Interaction {
input,
output: Captured::new(output.into()),
});
self
}
}
/// One-time interaction with the terminal.
#[derive(Debug, Clone)]
pub struct Interaction<Out: TermOutput = Captured> {
input: UserInput,
output: Out,
}
impl<Out: TermOutput> Interaction<Out> {
/// Input provided by the user.
pub fn input(&self) -> &UserInput {
&self.input
}
/// Output to the terminal.
pub fn output(&self) -> &Out {
&self.output
}
}
/// User input during interaction with a terminal.
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "svg", derive(serde::Serialize))]
pub struct UserInput {
text: String,
prompt: Option<Cow<'static, str>>,
}
impl UserInput {
#[cfg(feature = "test")]
pub(crate) fn intern_prompt(prompt: String) -> Cow<'static, str> {
match prompt.as_str() {
"$" => Cow::Borrowed("$"),
">>>" => Cow::Borrowed(">>>"),
"..." => Cow::Borrowed("..."),
_ => Cow::Owned(prompt),
}
}
/// Creates a command.
pub fn command(text: impl Into<String>) -> Self {
Self {
text: text.into(),
prompt: Some(Cow::Borrowed("$")),
}
}
/// Creates a standalone / starting REPL command with the `>>>` prompt.
pub fn repl(text: impl Into<String>) -> Self {
Self {
text: text.into(),
prompt: Some(Cow::Borrowed(">>>")),
}
}
/// Creates a REPL command continuation with the `...` prompt.
pub fn repl_continuation(text: impl Into<String>) -> Self {
Self {
text: text.into(),
prompt: Some(Cow::Borrowed("...")),
}
}
/// Gets the kind of this input.
pub fn prompt(&self) -> Option<&str> {
self.prompt.as_deref()
}
}
impl AsRef<str> for UserInput {
fn as_ref(&self) -> &str {
&self.text
}
}
impl From<&str> for UserInput {
fn from(command: &str) -> Self {
Self::command(command)
}
}
// Necessary to make it possible to call `TestConfig::test()` with a &[&str].
impl From<&&str> for UserInput {
fn from(command: &&str) -> Self {
Self::command(*command)
}
}
#[cfg(doctest)]
doc_comment::doctest!("../README.md");