assert_cmd/
lib.rs

1//! **Assert [`Command`]** - Easy command initialization and assertions.
2//!
3//! `assert_cmd` aims to simplify the process for doing integration testing of CLIs, including:
4//! - Finding your crate's binary to test
5//! - Assert on the result of your program's run.
6//!
7//! ## Overview
8//!
9//! Create a [`Command`]:
10//! - `Command::new(path)`
11//! - `Command::from_std(...)`
12//! - `Command::cargo_bin(name)`
13//!
14//! Configure a [`Command`]:
15//! - `arg` / `args`
16//! - `current_dir`
17//! - `env` / `envs` / `env_remove` / `env_clear`
18//! - `write_stdin` / `pipe_stdin`
19//! - `timeout`
20//!
21//! Validate a [`Command`]:
22//! - `ok` / `unwrap` / `unwrap_err`
23//! - `assert`
24//!   - `success`, see [`Assert`]
25//!   - `failure`, see [`Assert`]
26//!   - `interrupted`, see [`Assert`]
27//!   - `code`, see [`Assert`]
28//!   - `stdout`, see [`Assert`]
29//!   - `stderr`, see [`Assert`]
30//!   - `get_output` for everything else, see [`Assert`]
31//!
32//! Note: [`Command`] is provided as a convenience. Extension traits for [`std::process::Command`]
33//! and `Output` are provided for interoperability:
34//! - [`CommandCargoExt`]
35//! - [`OutputOkExt`]
36//! - [`OutputAssertExt`]
37//!
38//! ## Examples
39//!
40//! Here's a trivial example:
41//! ```rust,no_run
42//! use assert_cmd::Command;
43//!
44//! let mut cmd = Command::cargo_bin("bin_fixture").unwrap();
45//! cmd.assert().success();
46//! ```
47//!
48//! And a little of everything:
49//! ```rust,no_run
50//! use assert_cmd::Command;
51//!
52//! let mut cmd = Command::cargo_bin("bin_fixture").unwrap();
53//! let assert = cmd
54//!     .arg("-A")
55//!     .env("stdout", "hello")
56//!     .env("exit", "42")
57//!     .write_stdin("42")
58//!     .assert();
59//! assert
60//!     .failure()
61//!     .code(42)
62//!     .stdout("hello\n");
63//! ```
64//!
65//! ## Relevant crates
66//!
67//! Other crates that might be useful in testing command line programs.
68//! * [escargot] for more control over configuring the crate's binary.
69//! * [duct] for orchestrating multiple processes.
70//!   * or [commandspec] for easier writing of commands
71//! * [rexpect][rexpect] for testing interactive programs.
72//! * [assert_fs] for filesystem fixtures and assertions.
73//!   * or [tempfile] for scratchpad directories.
74//! * [dir-diff] for testing file side-effects.
75//!
76//! ## Migrating from `assert_cli` v0.6
77//!
78//! `assert_cmd` is the successor to [the original `assert_cli`][assert_cli]:
79//! - More flexible, reusable assertions (also used by [assert_fs]).
80//! - Can integrate with other process-management crates, like `duct`.
81//! - Addresses several architectural problems.
82//!
83//! Key points in migrating from `assert_cli`:
84//! - The command-under-test is run eagerly, with assertions happening immediately.
85//! - [`success()`] is not implicit and requires being explicitly called.
86//! - `stdout`/`stderr` aren't automatically trimmed before being passed to the `Predicate`.
87//!
88//! [commandspec]: https://crates.io/crates/commandspec
89//! [assert_cli]: https://crates.io/crates/assert_cli/0.6.3
90//! [dir-diff]: https://crates.io/crates/dir-diff
91//! [tempfile]: https://crates.io/crates/tempfile
92//! [escargot]: https://crates.io/crates/escargot
93//! [duct]: https://crates.io/crates/duct
94//! [assert_fs]: https://crates.io/crates/assert_fs
95//! [rexpect]: https://crates.io/crates/rexpect
96//! [`Command`]: cmd::Command
97//! [`Assert`]: assert::Assert
98//! [`success()`]: assert::Assert::success()
99//! [`CommandCargoExt`]: cargo::CommandCargoExt
100//! [`OutputOkExt`]: output::OutputOkExt
101//! [`OutputAssertExt`]: assert::OutputAssertExt
102
103#![cfg_attr(docsrs, feature(doc_auto_cfg))]
104#![warn(clippy::print_stderr)]
105#![warn(clippy::print_stdout)]
106
107/// Allows you to pull the name from your Cargo.toml at compile time.
108///
109/// # Examples
110///
111/// ```should_panic
112/// use assert_cmd::Command;
113///
114/// let mut cmd = Command::cargo_bin(assert_cmd::crate_name!()).unwrap();
115/// let assert = cmd
116///     .arg("-A")
117///     .env("stdout", "hello")
118///     .env("exit", "42")
119///     .write_stdin("42")
120///     .assert();
121/// assert
122///     .failure()
123///     .code(42)
124///     .stdout("hello\n");
125/// ```
126#[macro_export]
127macro_rules! crate_name {
128    () => {
129        env!("CARGO_PKG_NAME")
130    };
131}
132
133pub mod assert;
134pub mod cargo;
135pub mod cmd;
136pub mod output;
137
138/// Extension traits that are useful to have available.
139pub mod prelude {
140    pub use crate::assert::OutputAssertExt;
141    pub use crate::cargo::CommandCargoExt;
142    pub use crate::output::OutputOkExt;
143}
144
145pub use crate::cmd::Command;
146
147mod color;
148use color::Palette;
149
150doc_comment::doctest!("../README.md");
assert_cmd/lib.rs

assert_cmd/
lib.rs
