Add assert_status_success, assert_status_success_false

src/assert_status/assert_status_success.rs

@@ -0,0 +1,217 @@
+//! Assert a status is a success.
+//!
+//! Pseudocode:<br>
+//! a ⇒ status ⇒ success = true
+//!
+//! # Example
+//!
+//! ```rust
+//! use assertables::*;
+//! use std::process::Command;
+//!
+//! # fn main() {
+//! let mut a = Command::new("bin/exit-with-arg"); a.arg("0");
+//! assert_status_success!(a);
+//! # }
+//! ```
+//!
+//! # Module macros
+//!
+//! * [`assert_status_success`](macro@crate::assert_status_success)
+//! * [`assert_status_success_as_result`](macro@crate::assert_status_success_as_result)
+//! * [`debug_assert_status_success`](macro@crate::debug_assert_status_success)
+
+/// Assert a status is a success.
+///
+/// Pseudocode:<br>
+/// a ⇒ status ⇒ success = true
+///
+/// * If true, return Result `Ok(a ⇒ status ⇒ code ⇒ value)`.
+///
+/// * Otherwise, return Result `Err(message)`.
+///
+/// This macro provides the same statements as [`assert_`](macro.assert_.html),
+/// except this macro returns a Result, rather than doing a panic.
+///
+/// This macro is useful for runtime checks, such as checking parameters,
+/// or sanitizing inputs, or handling different results in different ways.
+///
+/// # Module macros
+///
+/// * [`assert_status_success`](macro@crate::assert_status_success)
+/// * [`assert_status_success_as_result`](macro@crate::assert_status_success_as_result)
+/// * [`debug_assert_status_success`](macro@crate::debug_assert_status_success)
+///
+#[macro_export]
+macro_rules! assert_status_success_as_result {
+    ($a:expr $(,)?) => {{
+        match ($a.status()) {
+            Ok(a1) => {
+                if a1.success()  {
+                    Ok(true)
+                } else {
+                    Err(
+                        format!(
+                            concat!(
+                                "assertion failed: `assert_status_success!(a)`\n",
+                                "https://docs.rs/assertables/9.3.0/assertables/macro.assert_status_success.html\n",
+                                " a label: `{}`,\n",
+                                " a debug: `{:?}`",
+                            ),
+                            stringify!($a),
+                            $a,
+                        )
+                    )
+                }
+            },
+            a_status => {
+                Err(
+                    format!(
+                        concat!(
+                            "assertion failed: `assert_status_success!(a)`\n",
+                            "https://docs.rs/assertables/9.3.0/assertables/macro.assert_status_success.html\n",
+                            "  a label: `{}`,\n",
+                            "  a debug: `{:?}`,\n",
+                            " a status: `{:?}`",
+                        ),
+                        stringify!($a),
+                        $a,
+                        a_status
+                    )
+                )
+            }
+        }
+    }};
+}
+
+#[cfg(test)]
+mod tests {
+    use std::process::Command;
+
+    #[test]
+    fn success() {
+        let mut a = Command::new("bin/exit-with-arg");
+        a.arg("0");
+        let result = assert_status_success_as_result!(a);
+        assert_eq!(result.unwrap(), true);
+    }
+
+    #[test]
+    fn failure() {
+        let mut a = Command::new("bin/exit-with-arg");
+        a.arg("1");
+        let result = assert_status_success_as_result!(a);
+        assert_eq!(
+            result.unwrap_err(),
+            concat!(
+                "assertion failed: `assert_status_success!(a)`\n",
+                "https://docs.rs/assertables/9.3.0/assertables/macro.assert_status_success.html\n",
+                " a label: `a`,\n",
+                " a debug: `\"bin/exit-with-arg\" \"1\"`",
+            )
+        );
+    }
+}
+
+/// Assert a status is a success.
+///
+/// Pseudocode:<br>
+/// a ⇒ status ⇒ success = true
+///
+/// * If true, return `a ⇒ status ⇒ code ⇒ value``.
+///
+/// * Otherwise, call [`panic!`] with a message and the values of the
+///   expressions with their debug representations.
+///
+/// # Examples
+///
+/// ```rust
+/// use assertables::*;
+/// use std::process::Command;
+/// # use std::panic;
+///
+/// # fn main() {
+/// let mut a = Command::new("bin/exit-with-arg"); a.arg("0");
+/// assert_status_success!(a);
+///
+/// # let result = panic::catch_unwind(|| {
+/// // This will panic
+/// let mut a = Command::new("bin/exit-with-arg"); a.arg("1");
+/// assert_status_success!(a);
+/// # });
+/// // assertion failed: `assert_status_success!(a)`
+/// // https://docs.rs/assertables/9.3.0/assertables/macro.assert_status_success.html
+/// //  a label: `a`,
+/// //  a debug: `\"bin/exit-with-arg\" \"1\"`
+/// # let actual = result.unwrap_err().downcast::<String>().unwrap().to_string();
+/// # let expect = concat!(
+/// #     "assertion failed: `assert_status_success!(a)`\n",
+/// #     "https://docs.rs/assertables/9.3.0/assertables/macro.assert_status_success.html\n",
+/// #     " a label: `a`,\n",
+/// #     " a debug: `\"bin/exit-with-arg\" \"1\"`"
+/// # );
+/// # assert_eq!(actual, expect);
+/// # }
+/// ```
+///
+/// # Module macros
+///
+/// * [`assert_status_success`](macro@crate::assert_status_success)
+/// * [`assert_status_success_as_result`](macro@crate::assert_status_success_as_result)
+/// * [`debug_assert_status_success`](macro@crate::debug_assert_status_success)
+///
+#[macro_export]
+macro_rules! assert_status_success {
+    ($a:expr $(,)?) => {{
+        match $crate::assert_status_success_as_result!($a) {
+            Ok(x) => x,
+            Err(err) => panic!("{}", err),
+        }
+    }};
+    ($a:expr, $($message:tt)+) => {{
+        match $crate::assert_status_success_as_result!($a) {
+            Ok(x) => x,
+            Err(_err) => panic!("{}", $($message)+),
+        }
+    }};
+}
+
+/// Assert a status is a success.
+///
+/// Pseudocode:<br>
+/// a ⇒ status ⇒ success = true
+///
+/// This macro provides the same statements as [`assert_status_success`](macro.assert_status_success.html),
+/// except this macro's statements are only enabled in non-optimized
+/// builds by default. An optimized build will not execute this macro's
+/// statements unless `-C debug-assertions` is passed to the compiler.
+///
+/// This macro is useful for checks that are too expensive to be present
+/// in a release build but may be helpful during development.
+///
+/// The result of expanding this macro is always type checked.
+///
+/// An unchecked assertion allows a "bin/exit-with-arg" in an inconsistent state to
+/// keep running, which might have unexpected consequences but does not
+/// introduce unsafety as long as this only happens in safe code. The
+/// performance cost of assertions, however, is not measurable in general.
+/// Replacing `assert*!` with `debug_assert*!` is thus only encouraged
+/// after thorough profiling, and more importantly, only in safe code!
+///
+/// This macro is intended to work in a similar way to
+/// [`::std::debug_assert`](https://doc.rust-lang.org/std/macro.debug_assert.html).
+///
+/// # Module macros
+///
+/// * [`assert_status_success`](macro@crate::assert_status_success)
+/// * [`assert_status_success`](macro@crate::assert_status_success)
+/// * [`debug_assert_status_success`](macro@crate::debug_assert_status_success)
+///
+#[macro_export]
+macro_rules! debug_assert_status_success {
+    ($($arg:tt)*) => {
+        if $crate::cfg!(debug_assertions) {
+            $crate::assert_status_success!($($arg)*);
+        }
+    };
+}