term_transcript/shell/
mod.rs

1//! Shell-related types.
2
3use std::{
4    convert::Infallible,
5    env, error,
6    ffi::OsStr,
7    fmt, io,
8    path::{Path, PathBuf},
9    process::Command,
10    time::Duration,
11};
12
13use styled_str::StyledStr;
14
15mod standard;
16mod transcript_impl;
17
18pub use self::standard::StdShell;
19use crate::{
20    ExitStatus,
21    traits::{ConfigureCommand, Echoing, SpawnShell, SpawnedShell},
22};
23
24type StatusCheckerFn = dyn Fn(StyledStr<'_>) -> Option<ExitStatus>;
25
26pub(crate) struct StatusCheck {
27    command: String,
28    response_checker: Box<StatusCheckerFn>,
29}
30
31impl fmt::Debug for StatusCheck {
32    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
33        formatter
34            .debug_struct("StatusCheck")
35            .field("command", &self.command)
36            .finish_non_exhaustive()
37    }
38}
39
40impl StatusCheck {
41    pub(crate) fn command(&self) -> &str {
42        &self.command
43    }
44
45    pub(crate) fn check(&self, response: StyledStr<'_>) -> Option<ExitStatus> {
46        (self.response_checker)(response)
47    }
48}
49
50/// Options for executing commands in the shell. Used in [`Transcript::from_inputs()`]
51/// and in [`TestConfig`].
52///
53/// The type param maps to *extensions* available for the shell. For example, [`StdShell`]
54/// extension allows to specify custom aliases for the executed commands.
55///
56/// [`TestConfig`]: crate::test::TestConfig
57/// [`Transcript::from_inputs()`]: crate::Transcript::from_inputs()
58pub struct ShellOptions<Cmd = Command> {
59    command: Cmd,
60    path_additions: Vec<PathBuf>,
61    io_timeout: Duration,
62    init_timeout: Duration,
63    init_commands: Vec<String>,
64    line_decoder: Box<dyn FnMut(Vec<u8>) -> io::Result<String>>,
65    status_check: Option<StatusCheck>,
66}
67
68impl<Cmd: fmt::Debug> fmt::Debug for ShellOptions<Cmd> {
69    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
70        formatter
71            .debug_struct("ShellOptions")
72            .field("command", &self.command)
73            .field("path_additions", &self.path_additions)
74            .field("io_timeout", &self.io_timeout)
75            .field("init_timeout", &self.init_timeout)
76            .field("init_commands", &self.init_commands)
77            .field("status_check", &self.status_check)
78            .finish_non_exhaustive()
79    }
80}
81
82#[cfg(any(unix, windows))]
83impl Default for ShellOptions {
84    fn default() -> Self {
85        Self::new(Self::default_shell())
86    }
87}
88
89impl<Cmd: ConfigureCommand> From<Cmd> for ShellOptions<Cmd> {
90    fn from(command: Cmd) -> Self {
91        Self::new(command)
92    }
93}
94
95impl<Cmd: ConfigureCommand> ShellOptions<Cmd> {
96    #[cfg(unix)]
97    fn default_shell() -> Command {
98        Command::new("sh")
99    }
100
101    #[cfg(windows)]
102    fn default_shell() -> Command {
103        let mut command = Command::new("cmd");
104        // Switch off echoing user inputs and switch the codepage to UTF-8.
105        command.arg("/Q").arg("/K").arg("echo off && chcp 65001");
106        command
107    }
108
109    /// Creates new options with the provided `command`.
110    pub fn new(command: Cmd) -> Self {
111        Self {
112            command,
113            path_additions: vec![],
114            io_timeout: Duration::from_millis(500),
115            init_timeout: Duration::from_millis(1_500),
116            init_commands: vec![],
117            line_decoder: Box::new(|line| {
118                String::from_utf8(line)
119                    .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err.utf8_error()))
120            }),
121            status_check: None,
122        }
123    }
124
125    /// Sets the echoing flag for the shell.
126    #[must_use]
127    pub fn echoing(self, is_echoing: bool) -> ShellOptions<Echoing<Cmd>> {
128        ShellOptions {
129            command: Echoing::new(self.command, is_echoing),
130            path_additions: self.path_additions,
131            io_timeout: self.io_timeout,
132            init_timeout: self.init_timeout,
133            init_commands: self.init_commands,
134            line_decoder: self.line_decoder,
135            status_check: self.status_check,
136        }
137    }
138
139    /// Changes the current directory of the command.
140    #[must_use]
141    pub fn with_current_dir(mut self, current_dir: impl AsRef<Path>) -> Self {
142        self.command.current_dir(current_dir.as_ref());
143        self
144    }
145
146    /// Sets the I/O timeout for shell commands. This determines how long methods like
147    /// [`Transcript::from_inputs()`] wait
148    /// for output of a command before proceeding to the next command. Longer values
149    /// allow to capture output more accurately, but result in longer execution.
150    ///
151    /// By default, the I/O timeout is 0.5 seconds.
152    ///
153    /// [`Transcript::from_inputs()`]: crate::Transcript::from_inputs()
154    #[must_use]
155    pub fn with_io_timeout(mut self, io_timeout: Duration) -> Self {
156        self.io_timeout = io_timeout;
157        self
158    }
159
160    /// Sets an additional initialization timeout (relative to the one set by
161    /// [`Self::with_io_timeout()`]) before reading the output of the each command
162    /// input into the shell.
163    ///
164    /// By default, the initialization timeout is 1.5 seconds.
165    #[must_use]
166    pub fn with_init_timeout(mut self, init_timeout: Duration) -> Self {
167        self.init_timeout = init_timeout;
168        self
169    }
170
171    /// Adds an initialization command. Such commands are sent to the shell before executing
172    /// any user input. The corresponding output from the shell is not captured.
173    #[must_use]
174    pub fn with_init_command(mut self, command: impl Into<String>) -> Self {
175        self.init_commands.push(command.into());
176        self
177    }
178
179    /// Sets the `value` of an environment variable with the specified `name`.
180    #[must_use]
181    pub fn with_env(mut self, name: impl AsRef<str>, value: impl AsRef<OsStr>) -> Self {
182        self.command.env(name.as_ref(), value.as_ref());
183        self
184    }
185
186    /// Sets the line decoder for the shell. This allows for custom shell text encodings.
187    ///
188    /// The default decoder used is [the UTF-8 one](String::from_utf8()).
189    /// It halts processing with an error if the input is not UTF-8;
190    /// you may use [`Self::with_lossy_utf8_decoder()`] to swallow errors in this case.
191    #[must_use]
192    pub fn with_line_decoder<E, F>(mut self, mut mapper: F) -> Self
193    where
194        E: Into<Box<dyn error::Error + Send + Sync>>,
195        F: FnMut(Vec<u8>) -> Result<String, E> + 'static,
196    {
197        self.line_decoder = Box::new(move |line| {
198            mapper(line).map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))
199        });
200        self
201    }
202
203    /// Sets the [lossy UTF-8 decoder](String::from_utf8_lossy()) which always succeeds
204    /// at decoding at the cost of replacing non-UTF-8 chars.
205    #[must_use]
206    pub fn with_lossy_utf8_decoder(self) -> Self {
207        self.with_line_decoder::<Infallible, _>(|line| {
208            Ok(String::from_utf8_lossy(&line).into_owned())
209        })
210    }
211
212    /// Sets the [`ExitStatus`] checker for the shell. See `ExitStatus` docs for the semantics
213    /// of exit statuses.
214    ///
215    /// # Arguments
216    ///
217    /// - `command` is a command that will be executed to check the exit status of the latest
218    ///   executed command. E.g., in `sh`-like shells one can use `echo $?`.
219    /// - `checker` is a closure that transforms the output of `command` into an `ExitStatus`.
220    ///   The output is provided as a [`StyledStr`]; it usually makes sense to use
221    ///   [`StyledStr::text()`] to strip it of possible escape sequences (especially
222    ///   important if captured from PTY). If the exit status is inconclusive or not applicable,
223    ///   the closure should return `None`.
224    ///
225    /// The `command` will be executed after each [`UserInput`] is input into the shell and
226    /// the corresponding output is captured. After this, the [`StyledStr`]
227    /// output will be supplied to the `checker` closure and its output will be recorded as
228    /// [`Interaction::exit_status()`].
229    ///
230    /// [`UserInput`]: crate::UserInput
231    /// [`Interaction::exit_status()`]: crate::Interaction::exit_status()
232    ///
233    /// # Panics
234    ///
235    /// Panics if `command` contains newline chars (`'\n'` or `'\r'`).
236    #[must_use]
237    pub fn with_status_check<F>(mut self, command: impl Into<String>, checker: F) -> Self
238    where
239        F: Fn(StyledStr<'_>) -> Option<ExitStatus> + 'static,
240    {
241        let command = command.into();
242        assert!(
243            command.bytes().all(|ch| ch != b'\n' && ch != b'\r'),
244            "`command` contains a newline character ('\\n' or '\\r')"
245        );
246
247        self.status_check = Some(StatusCheck {
248            command,
249            response_checker: Box::new(checker),
250        });
251        self
252    }
253
254    // Gets the path to the cargo `target` dir. Adapted from cargo:
255    //
256    // https://github.com/rust-lang/cargo/blob/485670b3983b52289a2f353d589c57fae2f60f82/tests/testsuite/support/mod.rs#L507
257    fn target_path() -> PathBuf {
258        let mut path = env::current_exe().expect("Cannot obtain path to the executing file");
259        path.pop();
260        if path.ends_with("deps") {
261            path.pop();
262        }
263        path
264    }
265
266    /// Adds paths to cargo binaries (including examples) to the `PATH` env variable
267    /// for the shell described by these options.
268    /// This allows to call them by the corresponding filename, without specifying a path
269    /// or doing complex preparations (e.g., calling `cargo install`).
270    ///
271    /// # Limitations
272    ///
273    /// - The caller must be a unit or integration test; the method will work improperly otherwise.
274    #[must_use]
275    pub fn with_cargo_path(mut self) -> Self {
276        let target_path = Self::target_path();
277        self.path_additions.push(target_path.join("examples"));
278        self.path_additions.push(target_path);
279        self
280    }
281
282    /// Adds a specified path to the `PATH` env variable for the shell described by these options.
283    /// This method can be called multiple times to add multiple paths and is composable
284    /// with [`Self::with_cargo_path()`].
285    #[must_use]
286    pub fn with_additional_path(mut self, path: impl Into<PathBuf>) -> Self {
287        let path = path.into();
288        self.path_additions.push(path);
289        self
290    }
291}
292
293impl<Cmd: SpawnShell> ShellOptions<Cmd> {
294    #[cfg_attr(
295        feature = "tracing",
296        tracing::instrument(
297            level = "debug",
298            skip(self),
299            err,
300            fields(self.path_additions = ?self.path_additions)
301        )
302    )]
303    fn spawn_shell(&mut self) -> io::Result<SpawnedShell<Cmd>> {
304        #[cfg(unix)]
305        const PATH_SEPARATOR: &str = ":";
306        #[cfg(windows)]
307        const PATH_SEPARATOR: &str = ";";
308
309        if !self.path_additions.is_empty() {
310            let mut path_var = env::var_os("PATH").unwrap_or_default();
311            if !path_var.is_empty() {
312                path_var.push(PATH_SEPARATOR);
313            }
314            for (i, addition) in self.path_additions.iter().enumerate() {
315                path_var.push(addition);
316                if i + 1 < self.path_additions.len() {
317                    path_var.push(PATH_SEPARATOR);
318                }
319            }
320            self.command.env("PATH", &path_var);
321        }
322        self.command.spawn_shell()
323    }
324}
325
326#[cfg(test)]
327mod tests {
328    use super::*;
329    use crate::{Transcript, UserInput};
330
331    #[cfg(any(unix, windows))]
332    #[test]
333    fn creating_transcript_basics() -> anyhow::Result<()> {
334        let inputs = vec![
335            UserInput::command("echo hello"),
336            UserInput::command("echo foo && echo bar >&2"),
337        ];
338        let transcript = Transcript::from_inputs(&mut ShellOptions::default(), inputs)?;
339
340        assert_eq!(transcript.interactions().len(), 2);
341
342        {
343            let interaction = &transcript.interactions()[0];
344            assert_eq!(interaction.input().as_ref(), "echo hello");
345            assert_eq!(interaction.output().text().trim(), "hello");
346        }
347
348        let interaction = &transcript.interactions()[1];
349        assert_eq!(interaction.input().as_ref(), "echo foo && echo bar >&2");
350        let output = interaction.output();
351        assert_eq!(
352            output.text().split_whitespace().collect::<Vec<_>>(),
353            ["foo", "bar"]
354        );
355        Ok(())
356    }
357
358    #[cfg(unix)]
359    #[test]
360    fn transcript_with_multiline_input() -> anyhow::Result<()> {
361        let mut options = ShellOptions::default();
362        let inputs = vec![UserInput::command("echo \\\nhello")];
363        let transcript = Transcript::from_inputs(&mut options, inputs)?;
364
365        assert_eq!(transcript.interactions().len(), 1);
366        let interaction = &transcript.interactions()[0];
367        let output = interaction.output();
368        assert_eq!(output.text().trim(), "hello");
369        Ok(())
370    }
371}
term_transcript/shell/mod.rs

term_transcript/shell/
mod.rs
