diff --git a/src/assert.rs b/src/assert.rs index b02f075..82ac697 100644 --- a/src/assert.rs +++ b/src/assert.rs @@ -23,10 +23,10 @@ use cmd::output_fmt; /// /// use std::process::Command; /// -/// Command::main_binary() -/// .unwrap() -/// .assert() -/// .success(); +/// let mut cmd = Command::main_binary() +/// .unwrap(); +/// cmd.assert() +/// .success(); /// ``` /// /// [`Output`]: https://doc.rust-lang.org/std/process/struct.Output.html @@ -40,10 +40,10 @@ pub trait OutputAssertExt { /// /// use std::process::Command; /// - /// Command::main_binary() - /// .unwrap() - /// .assert() - /// .success(); + /// let mut cmd = Command::main_binary() + /// .unwrap(); + /// cmd.assert() + /// .success(); /// ``` /// /// [`Output`]: https://doc.rust-lang.org/std/process/struct.Output.html @@ -74,10 +74,10 @@ impl<'c> OutputAssertExt for &'c mut process::Command { /// /// use std::process::Command; /// -/// Command::main_binary() -/// .unwrap() -/// .assert() -/// .success(); +/// let mut cmd = Command::main_binary() +/// .unwrap(); +/// cmd.assert() +/// .success(); /// ``` /// /// [`Output`]: https://doc.rust-lang.org/std/process/struct.Output.html @@ -195,6 +195,7 @@ impl Assert { /// /// # Examples /// + /// Accepting a predicate: /// ```rust /// extern crate assert_cmd; /// extern crate predicates; @@ -211,7 +212,7 @@ impl Assert { /// .code(predicate::eq(42)); /// ``` /// - /// Shortcuts are also provided: + /// Accepting an exit code: /// ```rust /// use assert_cmd::prelude::*; /// @@ -224,10 +225,23 @@ impl Assert { /// .code(42); /// ``` /// + /// Accepting multiple exit codes: + /// ```rust + /// use assert_cmd::prelude::*; + /// + /// use std::process::Command; + /// + /// Command::main_binary() + /// .unwrap() + /// .env("exit", "42") + /// .assert() + /// .code(&[2, 42] as &[i32]); + /// ``` + /// /// - See [`predicates::prelude`] for more predicates. /// - See [`IntoCodePredicate`] for other built-in conversions. /// - /// [`predicates::prelude`]: https://docs.rs/predicates/0.9.0/predicates/prelude/ + /// [`predicates::prelude`]: https://docs.rs/predicates/1.0.0/predicates/prelude/ /// [`IntoCodePredicate`]: trait.IntoCodePredicate.html pub fn code(self, pred: I) -> Self where @@ -251,8 +265,17 @@ impl Assert { /// Ensure the command wrote the expected data to `stdout`. /// + /// This uses [`IntoOutputPredicate`] to provide short-hands for common cases. + /// + /// - See [`predicates::prelude`] for more predicates. + /// - See [`IntoOutputPredicate`] for other built-in conversions. + /// + /// [`predicates::prelude`]: https://docs.rs/predicates/1.0.0/predicates/prelude/ + /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html + /// /// # Examples /// + /// Accepting a bytes predicate: /// ```rust /// extern crate assert_cmd; /// extern crate predicates; @@ -267,28 +290,54 @@ impl Assert { /// .env("stdout", "hello") /// .env("stderr", "world") /// .assert() - /// .stdout(predicate::str::similar("hello\n").from_utf8()); + /// .stdout(predicate::eq(b"hello\n" as &[u8])); /// ``` /// - /// Shortcuts are also provided: + /// Accepting a `str` predicate: /// ```rust + /// extern crate assert_cmd; + /// extern crate predicates; + /// /// use assert_cmd::prelude::*; /// /// use std::process::Command; + /// use predicates::prelude::*; /// /// Command::main_binary() /// .unwrap() /// .env("stdout", "hello") /// .env("stderr", "world") /// .assert() - /// .stdout("hello\n"); + /// .stdout(predicate::str::similar("hello\n")); /// ``` /// - /// - See [`predicates::prelude`] for more predicates. - /// - See [`IntoOutputPredicate`] for other built-in conversions. + /// Accepting bytes: + /// ```rust + /// use assert_cmd::prelude::*; /// - /// [`predicates::prelude`]: https://docs.rs/predicates/0.9.0/predicates/prelude/ - /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html + /// use std::process::Command; + /// + /// Command::main_binary() + /// .unwrap() + /// .env("stdout", "hello") + /// .env("stderr", "world") + /// .assert() + /// .stdout(b"hello\n" as &[u8]); + /// ``` + /// + /// Accepting a `str`: + /// ```rust + /// use assert_cmd::prelude::*; + /// + /// use std::process::Command; + /// + /// Command::main_binary() + /// .unwrap() + /// .env("stdout", "hello") + /// .env("stderr", "world") + /// .assert() + /// .stdout("hello\n"); + /// ``` pub fn stdout(self, pred: I) -> Self where I: IntoOutputPredicate

, @@ -309,8 +358,17 @@ impl Assert { /// Ensure the command wrote the expected data to `stderr`. /// + /// This uses [`IntoOutputPredicate`] to provide short-hands for common cases. + /// + /// - See [`predicates::prelude`] for more predicates. + /// - See [`IntoOutputPredicate`] for other built-in conversions. + /// + /// [`predicates::prelude`]: https://docs.rs/predicates/1.0.0/predicates/prelude/ + /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html + /// /// # Examples /// + /// Accepting a bytes predicate: /// ```rust /// extern crate assert_cmd; /// extern crate predicates; @@ -325,28 +383,54 @@ impl Assert { /// .env("stdout", "hello") /// .env("stderr", "world") /// .assert() - /// .stderr(predicate::str::similar("world\n").from_utf8()); + /// .stderr(predicate::eq(b"world\n" as &[u8])); /// ``` /// - /// Shortcuts are also provided: + /// Accepting a `str` predicate: /// ```rust + /// extern crate assert_cmd; + /// extern crate predicates; + /// /// use assert_cmd::prelude::*; /// /// use std::process::Command; + /// use predicates::prelude::*; /// /// Command::main_binary() /// .unwrap() /// .env("stdout", "hello") /// .env("stderr", "world") /// .assert() - /// .stderr("world\n"); + /// .stderr(predicate::str::similar("world\n")); /// ``` /// - /// - See [`predicates::prelude`] for more predicates. - /// - See [`IntoOutputPredicate`] for other built-in conversions. + /// Accepting bytes: + /// ```rust + /// use assert_cmd::prelude::*; /// - /// [`predicates::prelude`]: https://docs.rs/predicates/0.9.0/predicates/prelude/ - /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html + /// use std::process::Command; + /// + /// Command::main_binary() + /// .unwrap() + /// .env("stdout", "hello") + /// .env("stderr", "world") + /// .assert() + /// .stderr(b"world\n" as &[u8]); + /// ``` + /// + /// Accepting a `str`: + /// ```rust + /// use assert_cmd::prelude::*; + /// + /// use std::process::Command; + /// + /// Command::main_binary() + /// .unwrap() + /// .env("stdout", "hello") + /// .env("stderr", "world") + /// .assert() + /// .stderr("world\n"); + /// ``` pub fn stderr(self, pred: I) -> Self where I: IntoOutputPredicate

, @@ -412,7 +496,7 @@ impl fmt::Debug for Assert { /// ``` /// /// [`Assert::code`]: struct.Assert.html#method.code -/// [`Predicate`]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [`Predicate`]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html pub trait IntoCodePredicate

where P: predicates_core::Predicate, @@ -438,8 +522,22 @@ where // Keep `predicates` concrete Predicates out of our public API. /// [Predicate] used by [`IntoCodePredicate`] for code. /// +/// # Example +/// +/// ```rust +/// use assert_cmd::prelude::*; +/// +/// use std::process::Command; +/// +/// Command::main_binary() +/// .unwrap() +/// .env("exit", "42") +/// .assert() +/// .code(42); +/// ``` +/// /// [`IntoCodePredicate`]: trait.IntoCodePredicate.html -/// [Predicate]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [Predicate]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html #[derive(Debug)] pub struct EqCodePredicate(predicates::ord::EqPredicate); @@ -494,8 +592,22 @@ impl IntoCodePredicate for i32 { // Keep `predicates` concrete Predicates out of our public API. /// [Predicate] used by [`IntoCodePredicate`] for iterables of codes. /// +/// # Example +/// +/// ```rust +/// use assert_cmd::prelude::*; +/// +/// use std::process::Command; +/// +/// Command::main_binary() +/// .unwrap() +/// .env("exit", "42") +/// .assert() +/// .code(&[2, 42] as &[i32]); +/// ``` +/// /// [`IntoCodePredicate`]: trait.IntoCodePredicate.html -/// [Predicate]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [Predicate]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html #[derive(Debug)] pub struct InCodePredicate(predicates::iter::InPredicate); @@ -587,7 +699,7 @@ impl IntoCodePredicate for &'static [i32] { /// /// [`Assert::stdout`]: struct.Assert.html#method.stdout /// [`Assert::stderr`]: struct.Assert.html#method.stderr -/// [`Predicate<[u8]>`]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [`Predicate<[u8]>`]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html pub trait IntoOutputPredicate

where P: predicates_core::Predicate<[u8]>, @@ -613,8 +725,23 @@ where // Keep `predicates` concrete Predicates out of our public API. /// [Predicate] used by [`IntoOutputPredicate`] for bytes. /// +/// # Example +/// +/// ```rust +/// use assert_cmd::prelude::*; +/// +/// use std::process::Command; +/// +/// Command::main_binary() +/// .unwrap() +/// .env("stdout", "hello") +/// .env("stderr", "world") +/// .assert() +/// .stderr(b"world\n" as &[u8]); +/// ``` +/// /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html -/// [Predicate]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [Predicate]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html #[derive(Debug)] pub struct BytesContentOutputPredicate(predicates::ord::EqPredicate<&'static [u8]>); @@ -669,8 +796,23 @@ impl IntoOutputPredicate for &'static [u8] { // Keep `predicates` concrete Predicates out of our public API. /// [Predicate] used by [`IntoOutputPredicate`] for [`str`]. /// +/// # Example +/// +/// ```rust +/// use assert_cmd::prelude::*; +/// +/// use std::process::Command; +/// +/// Command::main_binary() +/// .unwrap() +/// .env("stdout", "hello") +/// .env("stderr", "world") +/// .assert() +/// .stderr("world\n"); +/// ``` +/// /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html -/// [Predicate]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [Predicate]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html /// [`str`]: https://doc.rust-lang.org/std/primitive.str.html #[derive(Debug, Clone)] pub struct StrContentOutputPredicate( @@ -728,8 +870,27 @@ impl IntoOutputPredicate for &'static str { // Keep `predicates` concrete Predicates out of our public API. /// [Predicate] used by [`IntoOutputPredicate`] for [`Predicate`]. /// +/// # Example +/// +/// ```rust +/// extern crate assert_cmd; +/// extern crate predicates; +/// +/// use assert_cmd::prelude::*; +/// +/// use std::process::Command; +/// use predicates::prelude::*; +/// +/// Command::main_binary() +/// .unwrap() +/// .env("stdout", "hello") +/// .env("stderr", "world") +/// .assert() +/// .stderr(predicate::str::similar("world\n")); +/// ``` +/// /// [`IntoOutputPredicate`]: trait.IntoOutputPredicate.html -/// [Predicate]: https://docs.rs/predicates-core/0.9.0/predicates_core/trait.Predicate.html +/// [Predicate]: https://docs.rs/predicates-core/1.0.0/predicates_core/trait.Predicate.html #[derive(Debug, Clone)] pub struct StrOutputPredicate>( predicates::str::Utf8Predicate

, diff --git a/src/cargo.rs b/src/cargo.rs index 48ffdaa..2086c59 100644 --- a/src/cargo.rs +++ b/src/cargo.rs @@ -15,9 +15,9 @@ //! //! use std::process::Command; //! -//! Command::main_binary() -//! .unwrap() +//! let mut cmd = Command::main_binary() //! .unwrap(); +//! let output = cmd.unwrap(); //! ``` //! //! For caching to minimize cargo overhead or customize the build process, see [`escargot`]. @@ -37,8 +37,8 @@ //! .current_target() //! .run() //! .unwrap(); -//! bin_under_test.command() -//! .unwrap(); +//! let mut cmd = bin_under_test.command(); +//! let output = cmd.unwrap(); //! ``` //! //! Tip: Use [`lazy_static`] to cache `bin_under_test` across test functions. @@ -70,9 +70,9 @@ use escargot; /// /// use std::process::Command; /// -/// Command::main_binary() -/// .unwrap() +/// let mut cmd = Command::main_binary() /// .unwrap(); +/// let output = cmd.unwrap(); /// ``` /// /// [`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html @@ -92,9 +92,9 @@ where /// /// use std::process::Command; /// - /// Command::main_binary() - /// .unwrap() // get cargo binary - /// .unwrap(); // run it + /// let mut cmd = Command::main_binary() + /// .unwrap(); + /// let output = cmd.unwrap(); /// ``` /// /// [`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html @@ -109,9 +109,9 @@ where /// /// use std::process::Command; /// - /// Command::cargo_bin("bin_fixture") - /// .unwrap() + /// let mut cmd = Command::cargo_bin("bin_fixture") /// .unwrap(); + /// let output = cmd.unwrap(); /// ``` /// /// [`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html @@ -126,9 +126,9 @@ where /// /// use std::process::Command; /// - /// Command::cargo_example("example_fixture") - /// .unwrap() + /// let mut cmd = Command::cargo_example("example_fixture") /// .unwrap(); + /// let output = cmd.unwrap(); /// ``` /// /// [`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html diff --git a/src/lib.rs b/src/lib.rs index ed5ffb1..9d8b54d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,10 +9,33 @@ //! assert_cmd = "0.9" //! ``` //! -//! ## Example +//! ## Overview //! -//! Here's a trivial example: +//! Create a [`Command`]: +//! - `Command::new(path)`, see [`Command`] +//! - `Command::main_binary()`, see [`CommandCargoExt`] +//! - `Command::cargo_bin(name)`, see [`CommandCargoExt`] +//! - `Command::cargo_example(name)`, see [`CommandCargoExt`] +//! +//! Configure a [`Command`]: +//! - `arg` / `args`, see [`Command`] +//! - `current_dir`, see [`Command`] +//! - `env` / `envs` / `env_remove` / `env_clear`, see [`Command`] +//! - `with_stdin`, see [`CommandStdInExt`] +//! +//! Validate either a [`Command`] or `Output`: +//! - `ok` / `unwrap` / `unwrap_err`, see [`OutputOkExt`] +//! - `assert` ([`OutputAssertExt`]) +//! - `success`, see [`Assert`] +//! - `failure`, see [`Assert`] +//! - `interrupted`, see [`Assert`] +//! - `code`, see [`Assert`] +//! - `stdout`, see [`Assert`] +//! - `stderr`, see [`Assert`] +//! +//! ## Examples //! +//! Here's a trivial example: //! ```rust //! extern crate assert_cmd; //! @@ -25,6 +48,29 @@ //! } //! ``` //! +//! And a little of everything: +//! ```rust +//! extern crate assert_cmd; +//! +//! use std::process::Command; +//! use assert_cmd::prelude::*; +//! +//! fn main() { +//! let mut cmd = Command::main_binary().unwrap(); +//! cmd +//! .arg("-A") +//! .env("stdout", "hello") +//! .env("exit", "42") +//! .with_stdin() +//! .buffer("42"); +//! let assert = cmd.assert(); +//! assert +//! .failure() +//! .code(42) +//! .stdout("hello\n"); +//! } +//! ``` +//! //! ## Relevant crates //! //! Other crates that might be useful in testing command line programs. @@ -54,6 +100,7 @@ //! [duct]: https://crates.io/crates/duct //! [assert_fs]: https://crates.io/crates/assert_fs //! [`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html +//! [`Assert`]: struct.Assert.html //! [`success()`]: struct.Assert.html#method.success //! [`CommandCargoExt`]: cargo/trait.CommandCargoExt.html //! [`CommandStdInExt`]: trait.CommandStdInExt.html diff --git a/src/stdin.rs b/src/stdin.rs index 8ea6607..a9b3d48 100644 --- a/src/stdin.rs +++ b/src/stdin.rs @@ -30,11 +30,12 @@ pub trait CommandStdInExt { /// /// use std::process::Command; /// - /// Command::new("cat") + /// let mut cmd = Command::new("cat"); + /// cmd /// .arg("-A") /// .with_stdin() - /// .buffer("42") - /// .unwrap(); + /// .buffer("42"); + /// let output = cmd.unwrap(); /// ``` fn with_stdin(&mut self) -> StdInCommandBuilder; } @@ -63,11 +64,12 @@ impl<'a> StdInCommandBuilder<'a> { /// /// use std::process::Command; /// - /// Command::new("cat") + /// let mut cmd = Command::new("cat"); + /// cmd /// .arg("-A") /// .with_stdin() - /// .buffer("42") - /// .unwrap(); + /// .buffer("42"); + /// let output = cmd.unwrap(); /// ``` /// /// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html @@ -93,12 +95,13 @@ impl<'a> StdInCommandBuilder<'a> { /// /// use std::process::Command; /// - /// Command::new("cat") + /// let mut cmd = Command::new("cat"); + /// cmd /// .arg("-A") /// .with_stdin() /// .path("Cargo.toml") - /// .unwrap() /// .unwrap(); + /// let output = cmd.unwrap(); /// ``` /// /// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html @@ -129,10 +132,11 @@ impl<'a> StdInCommandBuilder<'a> { /// /// use std::process::Command; /// -/// Command::new("cat") +/// let mut cmd = Command::new("cat"); +/// cmd /// .with_stdin() -/// .buffer("42") -/// .unwrap(); +/// .buffer("42"); +/// let output = cmd.unwrap(); /// ``` /// /// [Command]: https://doc.rust-lang.org/std/process/struct.Command.html