Struct snapbox::cmd::Command

pub struct Command { /* private fields */ }

Process spawning for testing of non-interactive commands

Implementations

impl Command

Builder API

pub fn new(program: impl AsRef<OsStr>) -> Self

pub fn from_std(cmd: Command) -> Self

Constructs a new Command from a std Command.

pub fn with_assert(self, config: Assert) -> Self

Customize the assertion behavior

pub fn arg(self, arg: impl AsRef<OsStr>) -> Self

Adds an argument to pass to the program.

Only one argument can be passed per use. So instead of:

.arg("-C /path/to/repo")

usage would be:

.arg("-C")
.arg("/path/to/repo")

To pass multiple arguments see args.

Examples

Basic usage:

use snapbox::cmd::Command;

Command::new("ls")
        .arg("-l")
        .arg("-a")
        .assert()
        .success();

pub fn args(self, args: impl IntoIterator<Item = impl AsRef<OsStr>>) -> Self

Adds multiple arguments to pass to the program.

To pass a single argument see arg.

Examples

Basic usage:

use snapbox::cmd::Command;

Command::new("ls")
        .args(&["-l", "-a"])
        .assert()
        .success();

pub fn env(self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>) -> Self

Inserts or updates an environment variable mapping.

Note that environment variable names are case-insensitive (but case-preserving) on Windows, and case-sensitive on all other platforms.

Examples

Basic usage:

use snapbox::cmd::Command;

Command::new("ls")
        .env("PATH", "/bin")
        .assert()
        .failure();

pub fn envs(
    self,
    vars: impl IntoIterator<Item = (impl AsRef<OsStr>, impl AsRef<OsStr>)>
) -> Self

Adds or updates multiple environment variable mappings.

Examples

Basic usage:

use snapbox::cmd::Command;
use std::process::Stdio;
use std::env;
use std::collections::HashMap;

let filtered_env : HashMap<String, String> =
    env::vars().filter(|&(ref k, _)|
        k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH"
    ).collect();

Command::new("printenv")
        .env_clear()
        .envs(&filtered_env)
        .assert()
        .success();

pub fn env_remove(self, key: impl AsRef<OsStr>) -> Self

Removes an environment variable mapping.

Examples

Basic usage:

use snapbox::cmd::Command;

Command::new("ls")
        .env_remove("PATH")
        .assert()
        .failure();

pub fn env_clear(self) -> Self

Clears the entire environment map for the child process.

Examples

Basic usage:

use snapbox::cmd::Command;

Command::new("ls")
        .env_clear()
        .assert()
        .failure();

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

Sets the working directory for the child process.

Platform-specific behavior

If the program path is relative (e.g., "./script.sh"), it’s ambiguous whether it should be interpreted relative to the parent’s working directory or relative to current_dir. The behavior in this case is platform specific and unstable, and it’s recommended to use canonicalize to get an absolute program path instead.

Examples

Basic usage:

use snapbox::cmd::Command;

Command::new("ls")
        .current_dir("/bin")
        .assert()
        .success();

pub fn stdin(self, stream: impl Into<Data>) -> Self

Write buffer to stdin when the Command is run.

Examples

use snapbox::cmd::Command;

let mut cmd = Command::new("cat")
    .arg("-et")
    .stdin("42")
    .assert()
    .stdout_eq("42");

pub fn timeout(self, timeout: Duration) -> Self

Error out if a timeout is reached

use snapbox::cmd::Command;
use snapbox::cmd::cargo_bin;

let assert = Command::new(cargo_bin("snap-fixture"))
    .timeout(std::time::Duration::from_secs(1))
    .env("sleep", "100")
    .assert()
    .failure();

pub fn stderr_to_stdout(self) -> Self

Merge stderr into stdout

impl Command

Run Command

pub fn assert(self) -> OutputAssert

Run the command and assert on the results

use snapbox::cmd::Command;

let mut cmd = Command::new("cat")
    .arg("-et")
    .stdin("42")
    .assert()
    .stdout_eq("42");

pub fn output(self) -> Result<Output, Error>

Run the command and capture the Output

Trait Implementations

impl Debug for Command

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

Formats the value using the given formatter.

impl From<Command> for Command

fn from(cmd: Command) -> Self

Converts to this type from the input type.