term_transcript/test/
mod.rs

1//! Snapshot testing tools for [`Transcript`]s.
2//!
3//! # Examples
4//!
5//! Simple scenario in which the tested transcript calls to one or more Cargo binaries / examples
6//! by their original names.
7//!
8//! ```no_run
9//! use term_transcript::{
10//!     ShellOptions, Transcript,
11//!     test::{MatchKind, TestConfig, TestOutputConfig},
12//! };
13//!
14//! // Test configuration that can be shared across tests.
15//! fn config() -> TestConfig {
16//!     let shell_options = ShellOptions::default().with_cargo_path();
17//!     TestConfig::new(shell_options)
18//!         .with_match_kind(MatchKind::Precise)
19//!         .with_output(TestOutputConfig::Verbose)
20//! }
21//!
22//! // Usage in tests:
23//! #[test]
24//! fn help_command() {
25//!     config().test("tests/__snapshots__/help.svg", &["my-command --help"]);
26//! }
27//! ```
28//!
29//! Use [`TestConfig::test_transcript()`] for more complex scenarios or increased control:
30//!
31//! ```
32//! use term_transcript::{test::TestConfig, ShellOptions, Transcript, UserInput};
33//! # use term_transcript::svg::Template;
34//! use std::io;
35//!
36//! fn read_svg_file() -> anyhow::Result<impl io::BufRead> {
37//!     // snipped...
38//! #   let transcript = Transcript::from_inputs(
39//! #        &mut ShellOptions::default(),
40//! #        vec![UserInput::command(r#"echo "Hello world!""#)],
41//! #   )?;
42//! #   let mut writer = vec![];
43//! #   Template::default().render(&transcript, &mut writer)?;
44//! #   Ok(io::Cursor::new(writer))
45//! }
46//!
47//! # fn main() -> anyhow::Result<()> {
48//! let reader = read_svg_file()?;
49//! let transcript = Transcript::from_svg(reader)?;
50//! TestConfig::new(ShellOptions::default()).test_transcript(&transcript);
51//! # Ok(())
52//! # }
53//! ```
54
55use std::process::Command;
56#[cfg(feature = "svg")]
57use std::{env, ffi::OsStr};
58
59use anstream::ColorChoice;
60
61pub use self::{
62    config_impl::compare_transcripts,
63    parser::{LocatedParseError, ParseError},
64};
65#[cfg(feature = "svg")]
66use crate::svg::Template;
67use crate::{ShellOptions, Transcript, traits::SpawnShell};
68
69mod config_impl;
70mod parser;
71#[cfg(test)]
72mod tests;
73mod utils;
74
75/// Configuration of output produced during testing.
76#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
77#[non_exhaustive]
78pub enum TestOutputConfig {
79    /// Do not output anything.
80    Quiet,
81    /// Output normal amount of details.
82    #[default]
83    Normal,
84    /// Output more details.
85    Verbose,
86}
87
88/// Strategy for saving a new snapshot on a test failure within [`TestConfig::test()`] and
89/// related methods.
90#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
91#[non_exhaustive]
92#[cfg(feature = "svg")]
93#[cfg_attr(docsrs, doc(cfg(feature = "svg")))]
94pub enum UpdateMode {
95    /// Never create a new snapshot on test failure.
96    Never,
97    /// Always create a new snapshot on test failure.
98    Always,
99}
100
101#[cfg(feature = "svg")]
102impl UpdateMode {
103    /// Reads the update mode from the `TERM_TRANSCRIPT_UPDATE` env variable.
104    ///
105    /// If the `TERM_TRANSCRIPT_UPDATE` variable is not set, the output depends on whether
106    /// the executable is running in CI (which is detected by the presence of
107    /// the `CI` env variable):
108    ///
109    /// - In CI, the method returns [`Self::Never`].
110    /// - Otherwise, the method returns [`Self::Always`].
111    ///
112    /// # Panics
113    ///
114    /// If the `TERM_TRANSCRIPT_UPDATE` env variable is set to an unrecognized value
115    /// (something other than `never` or `always`), this method will panic.
116    pub fn from_env() -> Self {
117        const ENV_VAR: &str = "TERM_TRANSCRIPT_UPDATE";
118
119        match env::var_os(ENV_VAR) {
120            Some(s) => Self::from_os_str(&s).unwrap_or_else(|| {
121                panic!(
122                    "Cannot read update mode from env variable {ENV_VAR}: `{}` is not a valid value \
123                     (use one of `never` or `always`)",
124                    s.to_string_lossy()
125                );
126            }),
127            None => {
128                if env::var_os("CI").is_some() {
129                    Self::Never
130                } else {
131                    Self::Always
132                }
133            }
134        }
135    }
136
137    fn from_os_str(s: &OsStr) -> Option<Self> {
138        match s {
139            s if s == "never" => Some(Self::Never),
140            s if s == "always" => Some(Self::Always),
141            _ => None,
142        }
143    }
144
145    fn should_create_snapshot(self) -> bool {
146        match self {
147            Self::Always => true,
148            Self::Never => false,
149        }
150    }
151}
152
153/// Testing configuration.
154///
155/// # Examples
156///
157/// See the [module docs](crate::test) for the examples of usage.
158#[derive(Debug)]
159pub struct TestConfig<Cmd = Command, F = fn(&mut Transcript)> {
160    shell_options: ShellOptions<Cmd>,
161    match_kind: MatchKind,
162    output: TestOutputConfig,
163    color_choice: ColorChoice,
164    #[cfg(feature = "svg")]
165    update_mode: UpdateMode,
166    #[cfg(feature = "svg")]
167    template: Template,
168    transform: F,
169}
170
171impl<Cmd: SpawnShell> TestConfig<Cmd> {
172    /// Creates a new config.
173    ///
174    /// # Panics
175    ///
176    /// - Panics if the `svg` crate feature is enabled and the `TERM_TRANSCRIPT_UPDATE` variable
177    ///   is set to an incorrect value. See [`UpdateMode::from_env()`] for more details.
178    pub fn new(shell_options: ShellOptions<Cmd>) -> Self {
179        Self {
180            shell_options,
181            match_kind: MatchKind::TextOnly,
182            output: TestOutputConfig::Normal,
183            color_choice: ColorChoice::Auto,
184            #[cfg(feature = "svg")]
185            update_mode: UpdateMode::from_env(),
186            #[cfg(feature = "svg")]
187            template: Template::default(),
188            transform: |_| { /* do nothing */ },
189        }
190    }
191
192    /// Sets the transcript transform for these options. This can be used to transform the captured transcript
193    /// (e.g., to remove / replace uncontrollably varying data) before it's compared to the snapshot.
194    #[must_use]
195    pub fn with_transform<F>(self, transform: F) -> TestConfig<Cmd, F>
196    where
197        F: FnMut(&mut Transcript),
198    {
199        TestConfig {
200            shell_options: self.shell_options,
201            match_kind: self.match_kind,
202            output: self.output,
203            color_choice: self.color_choice,
204            #[cfg(feature = "svg")]
205            update_mode: self.update_mode,
206            #[cfg(feature = "svg")]
207            template: self.template,
208            transform,
209        }
210    }
211}
212
213impl<Cmd: SpawnShell, F: FnMut(&mut Transcript)> TestConfig<Cmd, F> {
214    /// Sets the matching kind applied.
215    #[must_use]
216    pub fn with_match_kind(mut self, kind: MatchKind) -> Self {
217        self.match_kind = kind;
218        self
219    }
220
221    /// Sets coloring of the output.
222    ///
223    /// On Windows, `color_choice` has slightly different semantics than its usage
224    /// in the `termcolor` crate. Namely, if colors can be used (stdout is a tty with
225    /// color support), ANSI escape sequences will always be used.
226    #[must_use]
227    pub fn with_color_choice(mut self, color_choice: ColorChoice) -> Self {
228        self.color_choice = color_choice;
229        self
230    }
231
232    /// Configures test output.
233    #[must_use]
234    pub fn with_output(mut self, output: TestOutputConfig) -> Self {
235        self.output = output;
236        self
237    }
238
239    /// Sets the template for rendering new snapshots.
240    #[cfg(feature = "svg")]
241    #[cfg_attr(docsrs, doc(cfg(feature = "svg")))]
242    #[must_use]
243    pub fn with_template(mut self, template: Template) -> Self {
244        self.template = template;
245        self
246    }
247
248    /// Overrides the strategy for saving new snapshots for failed tests.
249    ///
250    /// By default, the strategy is determined from the execution environment
251    /// using [`UpdateMode::from_env()`].
252    #[cfg(feature = "svg")]
253    #[cfg_attr(docsrs, doc(cfg(feature = "svg")))]
254    #[must_use]
255    pub fn with_update_mode(mut self, update_mode: UpdateMode) -> Self {
256        self.update_mode = update_mode;
257        self
258    }
259}
260
261/// Kind of terminal output matching.
262#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
263#[non_exhaustive]
264pub enum MatchKind {
265    /// Relaxed matching: compare only output text, but not coloring.
266    TextOnly,
267    /// Precise matching: compare output together with colors.
268    Precise,
269}
270
271/// Stats of a single snapshot test output by [`TestConfig::test_transcript_for_stats()`].
272#[derive(Debug, Clone)]
273pub struct TestStats {
274    // Match kind per each user input.
275    matches: Vec<Option<MatchKind>>,
276}
277
278impl TestStats {
279    /// Returns the number of successfully matched user inputs with at least the specified
280    /// `match_level`.
281    pub fn passed(&self, match_level: MatchKind) -> usize {
282        self.matches
283            .iter()
284            .filter(|&&kind| kind >= Some(match_level))
285            .count()
286    }
287
288    /// Returns the number of user inputs that do not match with at least the specified
289    /// `match_level`.
290    pub fn errors(&self, match_level: MatchKind) -> usize {
291        self.matches.len() - self.passed(match_level)
292    }
293
294    /// Returns match kinds per each user input of the tested [`Transcript`]. `None` values
295    /// mean no match.
296    ///
297    /// [`Transcript`]: crate::Transcript
298    pub fn matches(&self) -> &[Option<MatchKind>] {
299        &self.matches
300    }
301
302    /// Panics if these stats contain errors.
303    #[allow(clippy::missing_panics_doc)]
304    pub fn assert_no_errors(&self, match_level: MatchKind) {
305        assert_eq!(self.errors(match_level), 0, "There were test errors");
306    }
307}
term_transcript/test/mod.rs

term_transcript/test/
mod.rs
