Skip to content
This repository has been archived by the owner on Dec 29, 2021. It is now read-only.

Commit

Permalink
some doc changes
Browse files Browse the repository at this point in the history 
- explain asserting the exit codes
- better reflect the fact that `success` is expected by default
- tip/hint about the macro limitation
  • Loading branch information
@colin-kiegel
colin-kiegel committed Mar 22, 2017
1 parent 8a01125 commit e307b80
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 33 deletions.
16 changes: 11 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
```

Expand All @@ -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());
}
Expand All @@ -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();
}
Expand All @@ -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
Expand Down
90 changes: 62 additions & 28 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,7 @@
//!
//! ```rust
//! assert_cli::Assert::command(&["echo", "42"])
//! .succeeds()
//! .and().prints("42")
//! .prints("42")
//! .unwrap();
//! ```
//!
Expand All @@ -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!
//!
Expand All @@ -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());
//! # }
//! ```
Expand Down Expand Up @@ -175,7 +206,6 @@ impl Assert {
/// extern crate assert_cli;
///
/// assert_cli::Assert::command(&["echo", "1337"])
/// .succeeds()
/// .unwrap();
/// ```
pub fn command(cmd: &[&str]) -> Self {
Expand All @@ -194,7 +224,6 @@ impl Assert {
///
/// assert_cli::Assert::command(&["echo"])
/// .with_args(&["42"])
/// .succeeds()
/// .prints("42")
/// .unwrap();
/// ```
Expand All @@ -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 {
Expand All @@ -226,7 +255,6 @@ impl Assert {
/// extern crate assert_cli;
///
/// assert_cli::Assert::command(&["echo", "42"])
/// .succeeds()
/// .unwrap();
/// ```
pub fn succeeds(mut self) -> Self {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -271,7 +303,7 @@ impl Assert {
self
}

/// Expect the command's output to contain `output`.
/// Expect the command's output to **contain** `output`.
///
/// # Examples
///
Expand All @@ -290,7 +322,7 @@ impl Assert {
self
}

/// Expect the command to output exactly this `output`.
/// Expect the command to output **exactly** this `output`.
///
/// # Examples
///
Expand All @@ -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<O: Into<String>>(mut self, output: O) -> Self {
Expand All @@ -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<O: Into<String>>(mut self, output: O) -> Self {
Expand All @@ -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());
/// ```
Expand Down

0 comments on commit e307b80

Please sign in to comment.