Struct assert_cmd::cmd::Command

pub struct Command { /* fields omitted */ }

std::process::Command customized for testing.

Implementations

impl Command

pub fn from_std(cmd: Command) -> Self

Constructs a new Command from a std Command.

pub fn cargo_bin<S: AsRef<str>>(name: S) -> Result<Self, CargoError>

Create a Command to run a specific binary of the current crate.

See the [cargo module documentation][cargo] for caveats and workarounds.

Examples

use assert_cmd::Command;

let mut cmd = Command::cargo_bin(env!("CARGO_PKG_NAME"))
    .unwrap();
let output = cmd.unwrap();
println!("{:?}", output);

use assert_cmd::Command;

let mut cmd = Command::cargo_bin("bin_fixture")
    .unwrap();
let output = cmd.unwrap();
println!("{:?}", output);

pub fn write_stdin<S>(&mut self, buffer: S) -> &mut Self where
    S: Into<Vec<u8>>, 

Write buffer to stdin when the Command is run.

Examples

use assert_cmd::Command;

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

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

Error out if a timeout is reached

use assert_cmd::Command;

let assert = Command::cargo_bin("bin_fixture")
    .unwrap()
    .timeout(std::time::Duration::from_secs(1))
    .env("sleep", "100")
    .assert();
assert.failure();

pub fn pipe_stdin<P>(&mut self, file: P) -> Result<&mut Self> where
    P: AsRef<Path>, 

Write paths content to stdin when the Command is run.

Paths are relative to the env::current_dir and not Command::current_dir.

pub fn ok(&mut self) -> OutputResult

Run a Command, returning an OutputResult.

Examples

use assert_cmd::Command;

let result = Command::new("echo")
    .args(&["42"])
    .ok();
assert!(result.is_ok());

pub fn unwrap(&mut self) -> Output

Run a Command, unwrapping the OutputResult.

Examples

use assert_cmd::Command;

let output = Command::new("echo")
    .args(&["42"])
    .unwrap();

pub fn unwrap_err(&mut self) -> OutputError

Run a Command, unwrapping the error in the OutputResult.

Examples

use assert_cmd::Command;

let err = Command::new("a-command")
    .args(&["--will-fail"])
    .unwrap_err();

pub fn assert(&mut self) -> Assert

Run a Command and make assertions on the Output.

Examples

use assert_cmd::Command;

let mut cmd = Command::cargo_bin("bin_fixture")
    .unwrap()
    .assert()
    .success();

impl Command

Mirror std::process::Command's API

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

Constructs a new Command for launching the program at path program, with the following default configuration:

• No arguments to the program
• Inherit the current process's environment
• Inherit the current process's working directory
• Inherit stdin/stdout/stderr for spawn or status, but create pipes for output

Builder methods are provided to change these defaults and otherwise configure the process.

If program is not an absolute path, the PATH will be searched in an OS-defined way.

The search path to be used may be controlled by setting the PATH environment variable on the Command, but this has some implementation limitations on Windows (see issue #37519).

Examples

Basic usage:

use assert_cmd::Command;

Command::new("sh").unwrap();

pub fn arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut 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 assert_cmd::Command;

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

pub fn args<I, S>(&mut self, args: I) -> &mut Self where
    I: IntoIterator<Item = S>,
    S: AsRef<OsStr>, 

Adds multiple arguments to pass to the program.

To pass a single argument see arg.

Examples

Basic usage:

use assert_cmd::Command;

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

pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Self where
    K: AsRef<OsStr>,
    V: AsRef<OsStr>, 

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 assert_cmd::Command;

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

pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Self where
    I: IntoIterator<Item = (K, V)>,
    K: AsRef<OsStr>,
    V: AsRef<OsStr>, 

Adds or updates multiple environment variable mappings.

Examples

Basic usage:

use assert_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)
        .unwrap();

pub fn env_remove<K: AsRef<OsStr>>(&mut self, key: K) -> &mut Self

Removes an environment variable mapping.

Examples

Basic usage:

use assert_cmd::Command;

Command::new("ls")
        .env_remove("PATH")
        .unwrap_err();

pub fn env_clear(&mut self) -> &mut Self

Clears the entire environment map for the child process.

Examples

Basic usage:

use assert_cmd::Command;

Command::new("ls")
        .env_clear()
        .unwrap_err();

pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut 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 assert_cmd::Command;

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

pub fn output(&mut self) -> Result<Output>

Executes the Command as a child process, waiting for it to finish and collecting all of its output.

By default, stdout and stderr are captured (and used to provide the resulting output). Stdin is not inherited from the parent and any attempt by the child process to read from the stdin stream will result in the stream immediately closing.

Examples

use assert_cmd::Command;
use std::io::{self, Write};
let output = Command::new("/bin/cat")
                     .arg("file.txt")
                     .output()
                     .expect("failed to execute process");

println!("status: {}", output.status);
io::stdout().write_all(&output.stdout).unwrap();
io::stderr().write_all(&output.stderr).unwrap();

assert!(output.status.success());

Trait Implementations

impl CommandCargoExt for Command

fn cargo_bin<S: AsRef<str>>(name: S) -> Result<Self, CargoError>

Create a Command to run a specific binary of the current crate.

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

Performs the conversion.

impl<'c> OutputAssertExt for &'c mut Command

fn assert(self) -> Assert

Wrap with an interface for that provides assertions on the Output.

impl<'c> OutputOkExt for &'c mut Command

fn ok(self) -> OutputResult

Convert an Output to an OutputResult.

fn unwrap_err(self) -> OutputError

Unwrap a Output but with a prettier message than ok().err().unwrap().

fn unwrap(self) -> Output

Unwrap a Output but with a prettier message than .ok().unwrap().