From e307b80f9c1bd48fd991a5443b394f2bb2d0ca20 Mon Sep 17 00:00:00 2001 From: Colin Kiegel Date: Wed, 22 Mar 2017 23:56:52 +0100 Subject: [PATCH] some doc changes - explain asserting the exit codes - better reflect the fact that `success` is expected by default - tip/hint about the macro limitation --- README.md | 16 +++++++--- src/lib.rs | 90 +++++++++++++++++++++++++++++++++++++----------------- 2 files changed, 73 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index e3f787e..ae97974 100644 --- a/README.md +++ b/README.md @@ -25,13 +25,13 @@ fn main() { } ``` -Or if you'd rather use the macro: +Or if you'd rather use the macro, to save you some writing: ```rust #[macro_use] extern crate assert_cli; fn main() { - assert_cmd!(echo 42).succeeds().and().prints("42").unwrap(); + assert_cmd!(echo "42").prints("42").unwrap(); } ``` @@ -42,8 +42,10 @@ And here is one that will fail (which also shows `execute` which returns a #[macro_use] extern crate assert_cli; fn main() { - let test = assert_cmd!(grep amet "Cargo.toml") - .fails_with(1) + let test = assert_cmd!(ls "foo-bar-foo") + .fails() + .and() + .prints_error("foo-bar-foo") .execute(); assert!(test.is_ok()); } @@ -56,7 +58,7 @@ If you want to match the program's output _exactly_, you can use #[macro_use] extern crate assert_cli; fn main() { - assert_cmd!("wc" "README.md") + assert_cmd!(wc "README.md") .prints_exactly("1337 README.md") .unwrap(); } @@ -70,6 +72,10 @@ like this: +92 ``` +**Tip**: Enclose arguments in the `assert_cmd!` macro in quotes `"`, + if there are special characters, which the macro doesn't accept, e.g. + `assert_cmd!(cat "foo.txt")`. + More detailed information is available in the [documentation]. :-) ## License diff --git a/src/lib.rs b/src/lib.rs index 98f4787..80e28bc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,8 +18,7 @@ //! //! ```rust //! assert_cli::Assert::command(&["echo", "42"]) -//! .succeeds() -//! .and().prints("42") +//! .prints("42") //! .unwrap(); //! ``` //! @@ -38,25 +37,57 @@ //! +42 //! ``` //! -//! ## Assert CLI Crates +//! ## `assert_cmd!` Macro //! -//! If you are testing a Rust binary crate, you can start with -//! `Assert::main_binary()` to use `cargo run` as command. Or, if you want to -//! run a specific binary (if you have more than one), use -//! `Assert::cargo_binary`. +//! Alternatively, you can use the `assert_cmd!` macro to construct the command more conveniently, +//! but please carefully read the limitations below, or this may seriously go wrong. //! -//! ## `assert_cmd!` Macro +//! ```rust +//! # #[macro_use] extern crate assert_cli; +//! # fn main() { +//! assert_cmd!(echo "42").prints("42").unwrap(); +//! # } +//! ``` +//! +//! **Tips** +//! +//! - Don't forget to import the crate with `#[macro_use]`. ;-) +//! - Enclose arguments in the `assert_cmd!` macro in quotes `"`, +//! if there are special characters, which the macro doesn't accept, e.g. +//! `assert_cmd!(cat "foo.txt")`. +//! +//! ## Exit Status //! -//! Alternatively, you can use the `assert_cmd!` macro to construct the command more conveniently: +//! All assertion default to checking that the command exited with success. +//! +//! However, when you expect a command to fail, you can express it like this: //! //! ```rust //! # #[macro_use] extern crate assert_cli; //! # fn main() { -//! assert_cmd!(echo 42).succeeds().prints("42").unwrap(); +//! assert_cmd!(cat "non-existing-file") +//! .fails() +//! .and() +//! .prints_error("non-existing-file") +//! .unwrap(); //! # } //! ``` //! -//! Don't forget to import the crate with `#[macro_use]`. ;-) +//! Some notes on this: +//! +//! - Use `fails_with` to assert a specific exit status. +//! - There is also a `succeeds` method, but this is already the implicit default +//! and can usually be omitted. +//! - We can inspect the output of **stderr** with `prints_error` and `prints_error_exactly`. +//! - The `and` method has no effect, other than to make everything more readable. +//! Feel free to use it. :-) +//! +//! ## Assert CLI Crates +//! +//! If you are testing a Rust binary crate, you can start with +//! `Assert::main_binary()` to use `cargo run` as command. Or, if you want to +//! run a specific binary (if you have more than one), use +//! `Assert::cargo_binary`. //! //! ## Don't Panic! //! @@ -66,7 +97,7 @@ //! ```rust //! # #[macro_use] extern crate assert_cli; //! # fn main() { -//! let x = assert_cmd!(echo 1337).prints_exactly("42").execute(); +//! let x = assert_cmd!(echo "1337").prints_exactly("42").execute(); //! assert!(x.is_err()); //! # } //! ``` @@ -175,7 +206,6 @@ impl Assert { /// extern crate assert_cli; /// /// assert_cli::Assert::command(&["echo", "1337"]) - /// .succeeds() /// .unwrap(); /// ``` pub fn command(cmd: &[&str]) -> Self { @@ -194,7 +224,6 @@ impl Assert { /// /// assert_cli::Assert::command(&["echo"]) /// .with_args(&["42"]) - /// .succeeds() /// .prints("42") /// .unwrap(); /// ``` @@ -211,7 +240,7 @@ impl Assert { /// extern crate assert_cli; /// /// assert_cli::Assert::command(&["echo", "42"]) - /// .succeeds().and().prints("42") + /// .prints("42") /// .unwrap(); /// ``` pub fn and(self) -> Self { @@ -226,7 +255,6 @@ impl Assert { /// extern crate assert_cli; /// /// assert_cli::Assert::command(&["echo", "42"]) - /// .succeeds() /// .unwrap(); /// ``` pub fn succeeds(mut self) -> Self { @@ -245,8 +273,10 @@ impl Assert { /// ```rust /// extern crate assert_cli; /// - /// assert_cli::Assert::command(&["cat", "non-exisiting-file"]) + /// assert_cli::Assert::command(&["cat", "non-existing-file"]) /// .fails() + /// .and() + /// .prints_error("non-existing-file") /// .unwrap(); /// ``` pub fn fails(mut self) -> Self { @@ -261,8 +291,10 @@ impl Assert { /// ```rust /// extern crate assert_cli; /// - /// assert_cli::Assert::command(&["cat", "non-exisiting-file"]) + /// assert_cli::Assert::command(&["cat", "non-existing-file"]) /// .fails_with(1) + /// .and() + /// .prints_error_exactly("cat: non-existing-file: No such file or directory") /// .unwrap(); /// ``` pub fn fails_with(mut self, expect_exit_code: i32) -> Self { @@ -271,7 +303,7 @@ impl Assert { self } - /// Expect the command's output to contain `output`. + /// Expect the command's output to **contain** `output`. /// /// # Examples /// @@ -290,7 +322,7 @@ impl Assert { self } - /// Expect the command to output exactly this `output`. + /// Expect the command to output **exactly** this `output`. /// /// # Examples /// @@ -309,16 +341,17 @@ impl Assert { self } - /// Expect the command's stderr output to contain `output`. + /// Expect the command's stderr output to **contain** `output`. /// /// # Examples /// /// ```rust /// extern crate assert_cli; /// - /// assert_cli::Assert::command(&["cat", "non-exisiting-file"]) + /// assert_cli::Assert::command(&["cat", "non-existing-file"]) /// .fails() - /// .prints_error("non-exisiting-file") + /// .and() + /// .prints_error("non-existing-file") /// .unwrap(); /// ``` pub fn prints_error>(mut self, output: O) -> Self { @@ -329,16 +362,17 @@ impl Assert { self } - /// Expect the command to output exactly this `output` to stderr. + /// Expect the command to output **exactly** this `output` to stderr. /// /// # Examples /// /// ```rust /// extern crate assert_cli; /// - /// assert_cli::Assert::command(&["cat", "non-exisiting-file"]) - /// .fails() - /// .prints_error_exactly("cat: non-exisiting-file: No such file or directory") + /// assert_cli::Assert::command(&["cat", "non-existing-file"]) + /// .fails_with(1) + /// .and() + /// .prints_error_exactly("cat: non-existing-file: No such file or directory") /// .unwrap(); /// ``` pub fn prints_error_exactly>(mut self, output: O) -> Self { @@ -357,7 +391,7 @@ impl Assert { /// extern crate assert_cli; /// /// let test = assert_cli::Assert::command(&["echo", "42"]) - /// .succeeds() + /// .prints("42") /// .execute(); /// assert!(test.is_ok()); /// ```