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