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