Merge pull request assert-rs#31 from epage/docs

Improve API clarify

Author: epage

src/assert.rs

@@ -7,7 +7,7 @@ use std::str;
 use predicates;
 use predicates::str::PredicateStrExt;
 
-use cmd::dump_buffer;
+use errors::dump_buffer;
 use errors::output_fmt;
 
 /// Assert the state of an `Output`.
@@ -51,7 +51,7 @@ impl OutputAssertExt for process::Output {
 impl<'c> OutputAssertExt for &'c mut process::Command {
     fn assert(self) -> Assert {
         let output = self.output().unwrap();
-        Assert::new(output).set_cmd(format!("{:?}", self))
+        Assert::new(output).append_context("command", format!("{:?}", self))
     }
 }
 
@@ -71,32 +71,26 @@ impl<'c> OutputAssertExt for &'c mut process::Command {
 ///     .assert()
 ///     .success();
 /// ```
-#[derive(Debug)]
 pub struct Assert {
     output: process::Output,
-    cmd: Option<String>,
-    stdin: Option<Vec<u8>>,
+    context: Vec<(&'static str, Box<fmt::Display>)>,
 }
 
 impl Assert {
     /// Create an `Assert` for a given `Output`.
     pub fn new(output: process::Output) -> Self {
         Self {
             output,
-            cmd: None,
-            stdin: None,
+            context: vec![],
         }
     }
 
-    /// Add the command line for additional context.
-    pub fn set_cmd(mut self, cmd: String) -> Self {
-        self.cmd = Some(cmd);
-        self
-    }
-
-    /// Add the `stdn` for additional context.
-    pub fn set_stdin(mut self, stdin: Vec<u8>) -> Self {
-        self.stdin = Some(stdin);
+    /// Clarify failures with additional context.
+    pub fn append_context<D>(mut self, name: &'static str, context: D) -> Self
+    where
+        D: fmt::Display + 'static,
+    {
+        self.context.push((name, Box::new(context)));
         self
     }
 
@@ -298,20 +292,21 @@ impl Assert {
 
 impl fmt::Display for Assert {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        if let Some(ref cmd) = self.cmd {
-            writeln!(f, "command=`{}`", cmd)?;
-        }
-        if let Some(ref stdin) = self.stdin {
-            if let Ok(stdin) = str::from_utf8(stdin) {
-                writeln!(f, "stdin=```{}```", stdin)?;
-            } else {
-                writeln!(f, "stdin=```{:?}```", stdin)?;
-            }
+        for &(ref name, ref context) in &self.context {
+            writeln!(f, "{}=`{}`", name, context)?;
         }
         output_fmt(&self.output, f)
     }
 }
 
+impl fmt::Debug for Assert {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        f.debug_struct("Assert")
+            .field("output", &self.output)
+            .finish()
+    }
+}
+
 /// Used by `Assert::code` to convert `Self` into the needed `Predicate<i32>`.
 ///
 /// # Examples

src/cargo.rs

@@ -1,6 +1,12 @@
 //! Simplify running `bin`s in a Cargo project.
 //!
-//! # Examples
+//! `CommandCargoExt` is an extension trait for `std::process::Command` to easily launch a crate's
+//! binaries.
+//!
+//! In addition, the underlying functions for looking up the crate's binaries are exposed to allow
+//! for optimizations, if needed.
+//!
+//! # Simple Example
 //!
 //! ```rust
 //! use assert_cmd::prelude::*;
@@ -11,6 +17,22 @@
 //!     .unwrap()
 //!     .unwrap();
 //! ```
+//!
+//! # Caching Example
+//!
+//! ```rust
+//! use assert_cmd::prelude::*;
+//!
+//! use std::process::Command;
+//!
+//! let bin_under_test = assert_cmd::cargo::main_binary_path().unwrap();
+//! Command::new(&bin_under_test)
+//!     .unwrap();
+//! ```
+//!
+//! Tip: Use [`lazy_static][lazy_static] to cache `bin_under_test` across test functions.
+//!
+//! [lazy_static]: https://crates.io/crates/lazy_static
 
 use std::error::Error;
 use std::ffi;

src/cmd.rs

@@ -1,6 +1,6 @@
 use std::process;
-use std::str;
 
+use errors::dump_buffer;
 use errors::OutputError;
 use errors::OutputResult;
 
@@ -116,11 +116,3 @@ impl<'c> OutputOkExt for &'c mut process::Command {
         }
     }
 }
-
-pub(crate) fn dump_buffer(buffer: &[u8]) -> String {
-    if let Ok(buffer) = str::from_utf8(buffer) {
-        buffer.to_string()
-    } else {
-        format!("{:?}", buffer)
-    }
-}

src/errors.rs

@@ -162,16 +162,47 @@ pub(crate) fn output_fmt(output: &process::Output, f: &mut fmt::Formatter) -> fm
     } else {
         writeln!(f, "code=<interrupted>")?;
     }
-    if let Ok(stdout) = str::from_utf8(&output.stdout) {
-        writeln!(f, "stdout=```{}```", stdout)?;
+
+    write!(f, "stdout=```")?;
+    write_buffer(&output.stdout, f)?;
+    writeln!(f, "```")?;
+
+    write!(f, "stderr=```")?;
+    write_buffer(&output.stderr, f)?;
+    writeln!(f, "```")?;
+
+    Ok(())
+}
+
+pub(crate) fn dump_buffer(buffer: &[u8]) -> String {
+    if let Ok(buffer) = str::from_utf8(buffer) {
+        buffer.to_string()
     } else {
-        writeln!(f, "stdout=```{:?}```", output.stdout)?;
+        format!("{:?}", buffer)
     }
-    if let Ok(stderr) = str::from_utf8(&output.stderr) {
-        writeln!(f, "stderr=```{}```", stderr)?;
+}
+
+pub(crate) fn write_buffer(buffer: &[u8], f: &mut fmt::Formatter) -> fmt::Result {
+    if let Ok(buffer) = str::from_utf8(buffer) {
+        write!(f, "{}", buffer)
     } else {
-        writeln!(f, "stderr=```{:?}```", output.stderr)?;
+        write!(f, "{:?}", buffer)
+    }
+}
+
+#[derive(Debug)]
+pub(crate) struct DebugBuffer {
+    buffer: Vec<u8>,
+}
+
+impl DebugBuffer {
+    pub(crate) fn new(buffer: Vec<u8>) -> Self {
+        DebugBuffer { buffer }
     }
+}
 
-    Ok(())
+impl fmt::Display for DebugBuffer {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write_buffer(&self.buffer, f)
+    }
 }

src/lib.rs

@@ -33,6 +33,19 @@
 //! [tempfile]: https://crates.io/crates/tempfile
 //! [duct]: https://crates.io/crates/duct
 //! [assert_fs]: https://crates.io/crates/assert_fs
+//!
+//! ## Migrating from `assert_cli` v0.6
+//!
+//! `assert_cli` is the successor to `assert_cli`:
+//! - More flexible, reusable assertions (also used by `assert_fs`).
+//! - Can integrate with other process-management crates, like `duct`.
+//! - Addresses several architectural problems.
+//!
+//! Key points in migrating from `assert_cli`:
+//! - `std::prcoess::Command` is extended with traits rather than being wrapping in custom logic.
+//! - The command-under-test is run eagerly, with assertions happening immediately.
+//! - `success()` is not implicit and requires being explicitly called.
+//! - `stdout`/`stderr` aren't automatically trimmed before being passed to the `Predicate`.
 
 #![warn(missing_docs)]
 

src/stdin.rs

@@ -7,8 +7,9 @@ use std::process;
 
 use assert::Assert;
 use assert::OutputAssertExt;
-use cmd::dump_buffer;
 use cmd::OutputOkExt;
+use errors::dump_buffer;
+use errors::DebugBuffer;
 use errors::OutputError;
 use errors::OutputResult;
 
@@ -189,7 +190,7 @@ impl<'c> OutputAssertExt for &'c mut StdInCommand<'c> {
     fn assert(self) -> Assert {
         let output = self.output().unwrap();
         Assert::new(output)
-            .set_cmd(format!("{:?}", self.cmd))
-            .set_stdin(self.stdin.clone())
+            .append_context("command", format!("{:?}", self.cmd))
+            .append_context("stdin", DebugBuffer::new(self.stdin.clone()))
     }
 }