assertables/assert_command/assert_command_stdout_eq_x.rs
1//! Assert a command stdout string is equal to an expression.
2//!
3//! Pseudocode:<br>
4//! (command ⇒ stdout) = (expr into string)
5//!
6//! # Example
7//!
8//! ```rust
9//! use assertables::*;
10//! use std::process::Command;
11//!
12//! let mut command = Command::new("bin/printf-stdout");
13//! command.args(["%s", "alfa"]);
14//! let bytes = vec![b'a', b'l', b'f', b'a'];
15//! assert_command_stdout_eq_x!(command, bytes);
16//! ```
17//!
18//! # Module macros
19//!
20//! * [`assert_command_stdout_eq_x`](macro@crate::assert_command_stdout_eq_x)
21//! * [`assert_command_stdout_eq_x_as_result`](macro@crate::assert_command_stdout_eq_x_as_result)
22//! * [`debug_assert_command_stdout_eq_x`](macro@crate::debug_assert_command_stdout_eq_x)
23
24/// Assert a command stdout string is equal to an expression.
25///
26/// Pseudocode:<br>
27/// (command ⇒ stdout) = (expr into string)
28///
29/// * If true, return Result `Ok(stdout)`.
30///
31/// * Otherwise, return Result `Err(message)`.
32///
33/// This macro is useful for runtime checks, such as checking parameters,
34/// or sanitizing inputs, or handling different results in different ways.
35///
36/// # Module macros
37///
38/// * [`assert_command_stdout_eq_x`](macro@crate::assert_command_stdout_eq_x)
39/// * [`assert_command_stdout_eq_x_as_result`](macro@crate::assert_command_stdout_eq_x_as_result)
40/// * [`debug_assert_command_stdout_eq_x`](macro@crate::debug_assert_command_stdout_eq_x)
41///
42#[macro_export]
43macro_rules! assert_command_stdout_eq_x_as_result {
44 ($a_command:expr, $b_expr:expr $(,)?) => {
45 match ($a_command.output(), &$b_expr) {
46 (Ok(a), b) => {
47 let a = a.stdout;
48 if a.eq(b) {
49 Ok(a)
50 } else {
51 Err(
52 format!(
53 concat!(
54 "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
55 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
56 " command label: `{}`,\n",
57 " command debug: `{:?}`,\n",
58 " command value: `{:?}`,\n",
59 " expr label: `{}`,\n",
60 " expr debug: `{:?}`,\n",
61 " expr value: `{:?}`"
62 ),
63 stringify!($a_command),
64 $a_command,
65 a,
66 stringify!($b_expr),
67 $b_expr,
68 b
69 )
70 )
71 }
72 },
73 (a, b) => {
74 Err(
75 format!(
76 concat!(
77 "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
78 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
79 " command label: `{}`,\n",
80 " command debug: `{:?}`,\n",
81 " command value: `{:?}`,\n",
82 " expr label: `{}`,\n",
83 " expr debug: `{:?}`,\n",
84 " expr value: `{:?}`",
85 ),
86 stringify!($a_command),
87 $a_command,
88 a,
89 stringify!($b_expr),
90 $b_expr,
91 b
92 )
93 )
94 }
95 }
96 };
97}
98
99#[cfg(test)]
100mod test_assert_command_stdout_eq_x_as_result {
101 use std::process::Command;
102
103 #[test]
104 fn eq() {
105 let mut a = Command::new("bin/printf-stdout");
106 a.args(["%s", "alfa"]);
107 let b = vec![b'a', b'l', b'f', b'a'];
108 let actual = assert_command_stdout_eq_x_as_result!(a, b);
109 assert_eq!(actual.unwrap(), vec![b'a', b'l', b'f', b'a']);
110 }
111
112 #[test]
113 fn gt() {
114 let mut a = Command::new("bin/printf-stdout");
115 a.args(["%s", "alfa"]);
116 let b = vec![b'z', b'z'];
117 let actual = assert_command_stdout_eq_x_as_result!(a, b);
118 let message = concat!(
119 "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
120 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
121 " command label: `a`,\n",
122 " command debug: `\"bin/printf-stdout\" \"%s\" \"alfa\"`,\n",
123 " command value: `[97, 108, 102, 97]`,\n",
124 " expr label: `b`,\n",
125 " expr debug: `[122, 122]`,\n",
126 " expr value: `[122, 122]`"
127 );
128 assert_eq!(actual.unwrap_err(), message);
129 }
130
131 #[test]
132 fn lt() {
133 let mut a = Command::new("bin/printf-stdout");
134 a.args(["%s", "alfa"]);
135 let b = vec![b'a', b'a'];
136 let actual = assert_command_stdout_eq_x_as_result!(a, b);
137 let message = concat!(
138 "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
139 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
140 " command label: `a`,\n",
141 " command debug: `\"bin/printf-stdout\" \"%s\" \"alfa\"`,\n",
142 " command value: `[97, 108, 102, 97]`,\n",
143 " expr label: `b`,\n",
144 " expr debug: `[97, 97]`,\n",
145 " expr value: `[97, 97]`"
146 );
147 assert_eq!(actual.unwrap_err(), message);
148 }
149}
150
151/// Assert a command stdout string is equal to an expression.
152///
153/// Pseudocode:<br>
154/// (command ⇒ stdout) = (expr into string)
155///
156/// * If true, return `(stdout)`.
157///
158/// * Otherwise, call [`panic!`] with a message and the values of the
159/// expressions with their debug representations.
160///
161/// # Examples
162///
163/// ```rust
164/// use assertables::*;
165/// # use std::panic;
166/// use std::process::Command;
167///
168/// # fn main() {
169/// let mut command = Command::new("bin/printf-stdout");
170/// command.args(["%s", "alfa"]);
171/// let bytes = vec![b'a', b'l', b'f', b'a'];
172/// assert_command_stdout_eq_x!(command, bytes);
173///
174/// # let result = panic::catch_unwind(|| {
175/// // This will panic
176/// let mut command = Command::new("bin/printf-stdout");
177/// command.args(["%s", "alfa"]);
178/// let bytes = vec![b'z', b'z'];
179/// assert_command_stdout_eq_x!(command, bytes);
180/// # });
181/// // assertion failed: `assert_command_stdout_eq_x!(command, expr)`
182/// // https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html
183/// // command label: `command`,
184/// // command debug: `\"bin/printf-stdout\" \"%s\" \"alfa\"`,
185/// // command value: `[97, 108, 102, 97]`,
186/// // expr label: `bytes`,
187/// // expr debug: `[122, 122]`,
188/// // expr value: `[122, 122]`
189/// # let actual = result.unwrap_err().downcast::<String>().unwrap().to_string();
190/// # let message = concat!(
191/// # "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
192/// # "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
193/// # " command label: `command`,\n",
194/// # " command debug: `\"bin/printf-stdout\" \"%s\" \"alfa\"`,\n",
195/// # " command value: `[97, 108, 102, 97]`,\n",
196/// # " expr label: `bytes`,\n",
197/// # " expr debug: `[122, 122]`,\n",
198/// # " expr value: `[122, 122]`"
199/// # );
200/// # assert_eq!(actual, message);
201/// # }
202/// ```
203///
204/// # Module macros
205///
206/// * [`assert_command_stdout_eq_x`](macro@crate::assert_command_stdout_eq_x)
207/// * [`assert_command_stdout_eq_x_as_result`](macro@crate::assert_command_stdout_eq_x_as_result)
208/// * [`debug_assert_command_stdout_eq_x`](macro@crate::debug_assert_command_stdout_eq_x)
209///
210#[macro_export]
211macro_rules! assert_command_stdout_eq_x {
212 ($a_command:expr, $b_expr:expr $(,)?) => {
213 match $crate::assert_command_stdout_eq_x_as_result!($a_command, $b_expr) {
214 Ok(x) => x,
215 Err(err) => panic!("{}", err),
216 }
217 };
218 ($a_command:expr, $b_expr:expr, $($message:tt)+) => {
219 match $crate::assert_command_stdout_eq_x_as_result!($a_command, $b_expr) {
220 Ok(x) => x,
221 Err(err) => panic!("{}\n{}", format_args!($($message)+), err),
222 }
223 };
224}
225
226#[cfg(test)]
227mod test_assert_command_stdout_eq_x {
228 use std::panic;
229 use std::process::Command;
230
231 #[test]
232 fn eq() {
233 let mut a = Command::new("bin/printf-stdout");
234 a.args(["%s", "alfa"]);
235 let b = vec![b'a', b'l', b'f', b'a'];
236 let actual = assert_command_stdout_eq_x!(a, b);
237 assert_eq!(actual, vec![b'a', b'l', b'f', b'a']);
238 }
239
240 #[test]
241 fn gt() {
242 let result = panic::catch_unwind(|| {
243 let mut a = Command::new("bin/printf-stdout");
244 a.args(["%s", "alfa"]);
245 let b = vec![b'z', b'z'];
246 let _actual = assert_command_stdout_eq_x!(a, b);
247 });
248 let message = concat!(
249 "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
250 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
251 " command label: `a`,\n",
252 " command debug: `\"bin/printf-stdout\" \"%s\" \"alfa\"`,\n",
253 " command value: `[97, 108, 102, 97]`,\n",
254 " expr label: `b`,\n",
255 " expr debug: `[122, 122]`,\n",
256 " expr value: `[122, 122]`"
257 );
258 assert_eq!(
259 result
260 .unwrap_err()
261 .downcast::<String>()
262 .unwrap()
263 .to_string(),
264 message
265 );
266 }
267
268 #[test]
269 fn lt() {
270 let result = panic::catch_unwind(|| {
271 let mut a = Command::new("bin/printf-stdout");
272 a.args(["%s", "alfa"]);
273 let b = vec![b'a', b'a'];
274 let _actual = assert_command_stdout_eq_x!(a, b);
275 });
276 let message = concat!(
277 "assertion failed: `assert_command_stdout_eq_x!(command, expr)`\n",
278 "https://docs.rs/assertables/9.5.5/assertables/macro.assert_command_stdout_eq_x.html\n",
279 " command label: `a`,\n",
280 " command debug: `\"bin/printf-stdout\" \"%s\" \"alfa\"`,\n",
281 " command value: `[97, 108, 102, 97]`,\n",
282 " expr label: `b`,\n",
283 " expr debug: `[97, 97]`,\n",
284 " expr value: `[97, 97]`"
285 );
286 assert_eq!(
287 result
288 .unwrap_err()
289 .downcast::<String>()
290 .unwrap()
291 .to_string(),
292 message
293 );
294 }
295}
296
297/// Assert a command stdout string is equal to an expression.
298///
299/// Pseudocode:<br>
300/// (command ⇒ stdout) = (expr into string)
301///
302/// This macro provides the same statements as [`assert_command_stdout_eq_x`](macro.assert_command_stdout_eq_x.html),
303/// except this macro's statements are only enabled in non-optimized
304/// builds by default. An optimized build will not execute this macro's
305/// statements unless `-C debug-assertions` is passed to the compiler.
306///
307/// This macro is useful for checks that are too expensive to be present
308/// in a release build but may be helpful during development.
309///
310/// The result of expanding this macro is always type checked.
311///
312/// An unchecked assertion allows a program in an inconsistent state to
313/// keep running, which might have unexpected consequences but does not
314/// introduce unsafety as long as this only happens in safe code. The
315/// performance cost of assertions, however, is not measurable in general.
316/// Replacing `assert*!` with `debug_assert*!` is thus only encouraged
317/// after thorough profiling, and more importantly, only in safe code!
318///
319/// This macro is intended to work in a similar way to
320/// [`::std::debug_assert`](https://doc.rust-lang.org/std/macro.debug_assert.html).
321///
322/// # Module macros
323///
324/// * [`assert_command_stdout_eq_x`](macro@crate::assert_command_stdout_eq_x)
325/// * [`assert_command_stdout_eq_x`](macro@crate::assert_command_stdout_eq_x)
326/// * [`debug_assert_command_stdout_eq_x`](macro@crate::debug_assert_command_stdout_eq_x)
327///
328#[macro_export]
329macro_rules! debug_assert_command_stdout_eq_x {
330 ($($arg:tt)*) => {
331 if $crate::cfg!(debug_assertions) {
332 $crate::assert_command_stdout_eq_x!($($arg)*);
333 }
334 };
335}