assert_cli/
lib.rs

1//! # Test CLI Applications
2//!
3//! This crate's goal is to provide you some very easy tools to test your CLI
4//! applications. It can currently execute child processes and validate their
5//! exit status as well as stdout and stderr output against your assertions.
6//!
7//! Include the crate like
8//!
9//! ```rust
10//! #[macro_use] // <-- import the convenience macro (optional)
11//! extern crate assert_cli;
12//! # fn main() { }
13//! ```
14//!
15//! ## Basic Examples
16//!
17//! Here's a trivial example:
18//!
19//! ```rust
20//! assert_cli::Assert::command(&["echo", "42"])
21//!     .stdout().contains("42")
22//!     .unwrap();
23//! ```
24//!
25//! And here is one that will fail:
26//!
27//! ```rust,should_panic
28//! assert_cli::Assert::command(&["echo", "42"])
29//!     .stdout().is("1337")
30//!     .unwrap();
31//! ```
32//!
33//! this will show a nice, colorful diff in your terminal, like this:
34//!
35//! ```diff
36//! -1337
37//! +42
38//! ```
39//!
40//! ## `assert_cmd!` Macro
41//!
42//! Alternatively, you can use the `assert_cmd!` macro to construct the command more conveniently,
43//! but please carefully read the limitations below, or this may seriously go wrong.
44//!
45//! ```rust
46//! # #[macro_use] extern crate assert_cli;
47//! # fn main() {
48//! assert_cmd!(echo "42").stdout().contains("42").unwrap();
49//! # }
50//! ```
51//!
52//! **Tips**
53//!
54//! - Don't forget to import the crate with `#[macro_use]`. ;-)
55//! - Enclose arguments in the `assert_cmd!` macro in quotes `"`,
56//!   if there are special characters, which the macro doesn't accept, e.g.
57//!   `assert_cmd!(cat "foo.txt")`.
58//!
59//! ## Exit Status
60//!
61//! All assertion default to checking that the command exited with success.
62//!
63//! However, when you expect a command to fail, you can express it like this:
64//!
65//! ```rust
66//! # #[macro_use] extern crate assert_cli;
67//! # fn main() {
68//! assert_cmd!(cat "non-existing-file")
69//!     .fails()
70//!     .unwrap();
71//! # }
72//! ```
73//!
74//! Some notes on this:
75//!
76//! - Use `fails_with` to assert a specific exit status.
77//! - There is also a `succeeds` method, but this is already the implicit default
78//!   and can usually be omitted.
79//! - The `and` method has no effect, other than to make everything more readable.
80//!   Feel free to use it. :-)
81//!
82//! ## stdout / stderr
83//!
84//! You can add assertions on the content of **stdout** and **stderr**.  They
85//! can be mixed together or even multiple of one stream can be used.
86//!
87//! ```rust
88//! # #[macro_use] extern crate assert_cli;
89//! # fn main() {
90//! assert_cmd!(echo "Hello world! The ansswer is 42.")
91//!     .stdout().contains("Hello world")
92//!     .stdout().contains("42")
93//!     .stderr().is("")
94//!     .unwrap();
95//! # }
96//! ```
97//!
98//! ## Assert CLI Crates
99//!
100//! If you are testing a Rust binary crate, you can start with
101//! `Assert::main_binary()` to use `cargo run` as command. Or, if you want to
102//! run a specific binary (if you have more than one), use
103//! `Assert::cargo_binary`.
104//!
105//! ## Don't Panic!
106//!
107//! If you don't want it to panic when the assertions are not met, simply call
108//! `.execute` instead of `.unwrap` to get a `Result`:
109//!
110//! ```rust
111//! # #[macro_use] extern crate assert_cli;
112//! # fn main() {
113//! let x = assert_cmd!(echo "1337").stdout().is("42").execute();
114//! assert!(x.is_err());
115//! # }
116//! ```
117
118#![deny(missing_docs)]
119
120extern crate colored;
121extern crate difference;
122extern crate environment;
123#[macro_use]
124extern crate failure;
125#[macro_use]
126extern crate failure_derive;
127extern crate serde_json;
128
129mod errors;
130pub use errors::AssertionError;
131
132#[macro_use]
133mod macros;
134pub use macros::flatten_escaped_string;
135
136mod assert;
137mod diff;
138mod output;
139
140pub use assert::Assert;
141pub use assert::OutputAssertionBuilder;
142/// Environment is a re-export of the Environment crate
143///
144/// It allow you to define/override environment variables for one or more assertions.
145pub use environment::Environment;
assert_cli/lib.rs

assert_cli/
lib.rs
