Struct Command

Source

pub struct Command { /* private fields */ }

Expand description

std::process::Command customized for testing.

Implementations§

Source §

impl Command

Mirror std::process::Command’s API

Source

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();

Source

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();

Source

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();

Source

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();

Source

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();

Source

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();

Source

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();

Source

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();

Source

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());

Source

pub fn get_program(&self) -> &OsStr

Returns the path to the program that was given to Command::new.

§Examples

Basic usage:

use assert_cmd::Command;

let cmd = Command::new("echo");
assert_eq!(cmd.get_program(), "echo");

Source

pub fn get_args(&self) -> CommandArgs<'_>

Returns an iterator of the arguments that will be passed to the program.

This does not include the path to the program as the first argument; it only includes the arguments specified with Command::arg and Command::args.

§Examples

Basic usage:

use std::ffi::OsStr;
use assert_cmd::Command;

let mut cmd = Command::new("echo");
cmd.arg("first").arg("second");
let args: Vec<&OsStr> = cmd.get_args().collect();
assert_eq!(args, &["first", "second"]);

Source

pub fn get_envs(&self) -> CommandEnvs<'_>

Returns an iterator of the environment variables explicitly set for the child process.

Environment variables explicitly set using Command::env, Command::envs, and Command::env_remove can be retrieved with this method.

Note that this output does not include environment variables inherited from the parent process.

Each element is a tuple key/value pair (&OsStr, Option<&OsStr>). A None value indicates its key was explicitly removed via Command::env_remove. The associated key for the None value will no longer inherit from its parent process.

An empty iterator can indicate that no explicit mappings were added or that Command::env_clear was called. After calling Command::env_clear, the child process will not inherit any environment variables from its parent process.

§Examples

Basic usage:

use std::ffi::OsStr;
use assert_cmd::Command;

let mut cmd = Command::new("ls");
cmd.env("TERM", "dumb").env_remove("TZ");
let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect();
assert_eq!(envs, &[
    (OsStr::new("TERM"), Some(OsStr::new("dumb"))),
    (OsStr::new("TZ"), None)
]);

Source

pub fn get_current_dir(&self) -> Option<&Path>

Returns the working directory for the child process.

This returns None if the working directory will not be changed.

§Examples

Basic usage:

use std::path::Path;
use assert_cmd::Command;

let mut cmd = Command::new("ls");
assert_eq!(cmd.get_current_dir(), None);
cmd.current_dir("/bin");
assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin")));