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