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