Struct term_transcript::ShellOptions

pub struct ShellOptions<Cmd = Command> { /* private fields */ }

Options for executing commands in the shell. Used in Transcript::from_inputs() and in TestConfig.

The type param maps to extensions available for the shell. For example, StdShell extension allows to specify custom aliases for the executed commands.

Implementations

impl ShellOptions<StdShell>

pub fn sh() -> Self

Creates options for an sh shell.

pub fn bash() -> Self

Creates options for a Bash shell.

pub fn pwsh() -> Self

Creates options for PowerShell 6+ (the one with the pwsh executable).

pub fn with_alias(self, name: &str, path_to_bin: &str) -> Self

Creates an alias for the binary at path_to_bin, which should be an absolute path. This allows to call the binary using this alias without complex preparations (such as installing it globally via cargo install), and is more flexible than Self::with_cargo_path().

In integration tests, you may use env!("CARGO_BIN_EXE_<name>") to get a path to binary targets.

Limitations

• For Bash and PowerShell, name must be a valid name of a function. For sh, name must be a valid name for the alias command. The name validity is not checked.

impl<Cmd: ConfigureCommand> ShellOptions<Cmd>

pub fn new(command: Cmd) -> Self

Creates new options with the provided command.

pub fn echoing(self, is_echoing: bool) -> ShellOptions<Echoing<Cmd>>

Sets the echoing flag for the shell.

pub fn with_current_dir(self, current_dir: impl AsRef<Path>) -> Self

Changes the current directory of the command.

pub fn with_io_timeout(self, io_timeout: Duration) -> Self

Sets the I/O timeout for shell commands. This determines how long methods like Transcript::from_inputs() wait for output of a command before proceeding to the next command. Longer values allow to capture output more accurately, but result in longer execution.

By default, the I/O timeout is 0.5 seconds.

pub fn with_init_timeout(self, init_timeout: Duration) -> Self

Sets an additional initialization timeout (relative to the one set by Self::with_io_timeout()) before reading the output of the each command input into the shell.

By default, the initialization timeout is 1.5 seconds.

pub fn with_init_command(self, command: impl Into<String>) -> Self

Adds an initialization command. Such commands are sent to the shell before executing any user input. The corresponding output from the shell is not captured.

pub fn with_env(self, name: impl AsRef<str>, value: impl AsRef<OsStr>) -> Self

Sets the value of an environment variable with the specified name.

pub fn with_line_decoder<E, F>(self, mapper: F) -> Self

where E: Into<Box<dyn Error + Send + Sync>>, F: FnMut(Vec<u8>) -> Result<String, E> + 'static,

Sets the line decoder for the shell. This allows for custom shell text encodings.

The default decoder used is the UTF-8 one. It halts processing with an error if the input is not UTF-8; you may use Self::with_lossy_utf8_decoder() to swallow errors in this case.

pub fn with_lossy_utf8_decoder(self) -> Self

Sets the lossy UTF-8 decoder which always succeeds at decoding at the cost of replacing non-UTF-8 chars.

pub fn with_status_check<F>( self, command: impl Into<String>, checker: F, ) -> Self

where F: Fn(&Captured) -> Option<ExitStatus> + 'static,

Sets the ExitStatus checker for the shell. See ExitStatus docs for the semantics of exit statuses.

Arguments

• command is a command that will be executed to check the exit status of the latest executed command. E.g., in sh-like shells one can use echo $?.
• checker is a closure that transforms the output of command into an ExitStatus. The output is provided as a Captured string; it usually makes sense to use Captured::to_plaintext() to strip it of possible escape sequences (especially important if captured from PTY). If the exit status is inconclusive or not applicable, the closure should return None.

The command will be executed after each UserInput is input into the shell and the corresponding output is captured. After this, the Captured output will be supplied to the checker closure and its output will be recorded as Interaction::exit_status().

Panics

Panics if command contains newline chars ('\n' or '\r').

pub fn with_cargo_path(self) -> Self

Adds paths to cargo binaries (including examples) to the PATH env variable for the shell described by these options. This allows to call them by the corresponding filename, without specifying a path or doing complex preparations (e.g., calling cargo install).

Limitations

• The caller must be a unit or integration test; the method will work improperly otherwise.

pub fn with_additional_path(self, path: impl Into<PathBuf>) -> Self

Adds a specified path to the PATH env variable for the shell described by these options. This method can be called multiple times to add multiple paths and is composable with Self::with_cargo_path().

Trait Implementations

impl<Cmd: Debug> Debug for ShellOptions<Cmd>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ShellOptions

fn default() -> Self

Returns the “default value” for a type.

impl<Cmd: ConfigureCommand> From<Cmd> for ShellOptions<Cmd>

fn from(command: Cmd) -> Self

Converts to this type from the input type.