1Test::Command(3) User Contributed Perl Documentation Test::Command(3)
2
3
4
6 Test::Command - Test routines for external commands
7
9 Version 0.11
10
12 Test the exit status, signal, STDOUT or STDERR of an external command.
13
14 use Test::Command tests => 11;
15
16 ## testing exit status
17
18 my $cmd = 'true';
19
20 exit_is_num($cmd, 0);
21 exit_cmp_ok($cmd, '<', 10);
22
23 $cmd = 'false';
24
25 exit_isnt_num($cmd, 0);
26
27 ## testing terminating signal
28
29 $cmd = 'true';
30
31 signal_is_num($cmd, 0);
32
33 ## testing STDOUT
34
35 $cmd = [qw/ echo out /]; ## run as "system @$cmd"
36 my $file_exp = 'echo_stdout.exp';
37
38 stdout_is_eq($cmd, "out\n");
39 stdout_isnt_eq($cmd, "out");
40 stdout_is_file($cmd, $file_exp);
41
42 ## testing STDERR
43
44 $cmd = 'echo err >&2';
45
46 stderr_like($cmd, /err/);
47 stderr_unlike($cmd, /rre/);
48 stderr_cmp_ok($cmd, 'eq', "err\n");
49
50 ## run-once-test-many-OO-style
51 ## the first test lazily runs command
52 ## the second test uses cached results
53
54 my $echo_test = Test::Command->new( cmd => 'echo out' );
55
56 $echo_test->exit_is_num(0);
57 $echo_test->signal_is_num(0);
58 $echo_test->stdout_is_eq("out\n");
59
60 ## force a re-run of the command
61
62 $echo_test->run;
63
64 ## arbitrary results inspection
65
66 is( $echo_test->exit_value, 0, 'echo exit' );
67 is( $echo_test->signal_value, undef, 'echo signal' );
68 is( $echo_test->stdout_value, "out\n", 'echo stdout' );
69 is( $echo_test->stderr_value, '', 'echo stderr' );
70 is( -s $echo_test->stdout_file, 4, 'echo stdout file size' );
71 is( -s $echo_test->stderr_file, 0, 'echo stderr file size' );
72
74 "Test::Command" intends to bridge the gap between the well tested
75 functions and objects you choose and their usage in your programs. By
76 examining the exit status, terminating signal, STDOUT and STDERR of
77 your program you can determine if it is behaving as expected.
78
79 This includes testing the various combinations and permutations of
80 options and arguments as well as the interactions between the various
81 functions and objects that make up your program.
82
83 The various test functions below can accept either a command string or
84 an array reference for the first argument. If the command is expressed
85 as a string it is passed to "system" as is. If the command is expressed
86 as an array reference it is dereferenced and passed to "system" as a
87 list. See '"perldoc -f system"' for how these may differ.
88
89 The final argument for the test functions, $name, is optional. By
90 default the $name is a concatenation of the test function name, the
91 command string and the expected value. This construction is generally
92 sufficient for identifying a failing test, but you may always specify
93 your own $name if desired.
94
95 Any of the test functions can be used as instance methods on a
96 "Test::Command" object. This is done by dropping the initial $cmd
97 argument and instead using arrow notation.
98
99 All of the following "exit_is_num" calls are equivalent.
100
101 exit_is_num('true', 0);
102 exit_is_num('true', 0, 'exit_is_num: true, 0');
103 exit_is_num(['true'], 0);
104 exit_is_num(['true'], 0, 'exit_is_num: true, 0');
105
106 my $cmd = Test::Command->new( cmd => 'true' );
107
108 exit_is_num($cmd, 0);
109 exit_is_num($cmd, 0, 'exit_is_num: true, 0');
110 $cmd->exit_is_num(0);
111 $cmd->exit_is_num(0, 'exit_is_num: true, 0');
112
113 $cmd = Test::Command->new( cmd => ['true'] );
114
115 exit_is_num($cmd, 0);
116 exit_is_num($cmd, 0, 'exit_is_num: true, 0');
117 $cmd->exit_is_num(0);
118 $cmd->exit_is_num(0, 'exit_is_num: true, 0');
119
121 All of the test functions mentioned below are exported by default.
122
124 new
125 my $test_cmd_obj = Test::Command->new( cmd => $cmd )
126
127 This constructor creates and returns a "Test::Command" object. Use this
128 to test multiple aspects of a single command execution while avoiding
129 repeatedly running commands which are slow or resource intensive.
130
131 The "cmd" parameter can accept either a string or an array reference
132 for its value. The value is dereferenced if necessary and passed
133 directly to the "system" builtin.
134
135 run
136 $test_cmd_obj->run;
137
138 This instance method forces the execution of the command specified by
139 the invocant.
140
141 You only need to call this when you wish to re-run a command since the
142 first test method invoked will lazily execute the command if necessary.
143 However, if the state of your inputs has changed and you wish to re-run
144 the command, you may do so by invoking this method at any point between
145 your tests.
146
148 Testing Exit Status
149 The test routines below compare against the exit status of the executed
150 command right shifted by 8 (that is, "$? >> 8").
151
152 exit_value
153
154 exit_value($cmd)
155
156 Return the exit status of the command. Useful for performing arbitrary
157 tests not covered by this module.
158
159 exit_is_num
160
161 exit_is_num($cmd, $exp_num, $name)
162
163 If the exit status of the command is numerically equal to the expected
164 number, this passes. Otherwise it fails.
165
166 exit_isnt_num
167
168 exit_isnt_num($cmd, $unexp_num, $name)
169
170 If the exit status of the command is not numerically equal to the given
171 number, this passes. Otherwise it fails.
172
173 exit_cmp_ok
174
175 exit_cmp_ok($cmd, $op, $operand, $name)
176
177 If the exit status of the command is compared with the given operand
178 using the given operator, and that operation returns true, this passes.
179 Otherwise it fails.
180
181 exit_is_defined
182
183 exit_is_defined($cmd, $name)
184
185 If the exit status of the command is defined, this passes. Otherwise it
186 fails. A defined exit status indicates that the command exited normally
187 by calling exit() or running off the end of the program.
188
189 exit_is_undef
190
191 exit_is_undef($cmd, $name)
192
193 If the exit status of the command is not defined, this passes.
194 Otherwise it fails. An undefined exit status indicates that the command
195 likely exited due to a signal.
196
197 Testing Terminating Signal
198 The test routines below compare against the lower 8 bits of the exit
199 status of the executed command.
200
201 signal_value
202
203 signal_value($cmd)
204
205 Return the signal code of the command. Useful for performing arbitrary
206 tests not covered by this module.
207
208 signal_is_num
209
210 signal_is_num($cmd, $exp_num, $name)
211
212 If the terminating signal of the command is numerically equal to the
213 expected number, this passes. Otherwise it fails.
214
215 signal_isnt_num
216
217 signal_isnt_num($cmd, $unexp_num, $name)
218
219 If the terminating signal of the command is not numerically equal to
220 the given number, this passes. Otherwise it fails.
221
222 signal_cmp_ok
223
224 signal_cmp_ok($cmd, $op, $operand, $name)
225
226 If the terminating signal of the command is compared with the given
227 operand using the given operator, and that operation returns true, this
228 passes. Otherwise it fails.
229
230 signal_is_defined
231
232 signal_is_defined($cmd, $name)
233
234 If the terminating signal of the command is defined, this passes.
235 Otherwise it fails. A defined signal indicates that the command likely
236 exited due to a signal.
237
238 signal_is_undef
239
240 signal_is_undef($cmd, $name)
241
242 If the terminating signal of the command is not defined, this passes.
243 Otherwise it fails. An undefined signal indicates that the command
244 exited normally by calling exit() or running off the end of the
245 program.
246
247 Testing STDOUT
248 Except where specified, the test routines below treat STDOUT as a
249 single slurped string.
250
251 stdout_value
252
253 stdout_value($cmd)
254
255 Return the STDOUT of the command. Useful for performing arbitrary tests
256 not covered by this module.
257
258 stdout_file
259
260 stdout_file($cmd)
261
262 Return the file name containing the STDOUT of the command. Useful for
263 performing arbitrary tests not covered by this module.
264
265 stdout_is_eq
266
267 stdout_is_eq($cmd, $exp_string, $name)
268
269 If the STDOUT of the command is equal (compared using "eq") to the
270 expected string, then this passes. Otherwise it fails.
271
272 stdout_isnt_eq
273
274 stdout_isnt_eq($cmd, $unexp_string, $name)
275
276 If the STDOUT of the command is not equal (compared using "eq") to the
277 given string, this passes. Otherwise it fails.
278
279 stdout_is_num
280
281 stdout_is_num($cmd, $exp_num, $name)
282
283 If the STDOUT of the command is equal (compared using "==") to the
284 expected number, then this passes. Otherwise it fails.
285
286 stdout_isnt_num
287
288 stdout_isnt_num($cmd, $unexp_num, $name)
289
290 If the STDOUT of the command is not equal (compared using "==") to the
291 given number, this passes. Otherwise it fails.
292
293 stdout_like
294
295 stdout_like($cmd, $exp_regex, $name)
296
297 If the STDOUT of the command matches the expected regular expression,
298 this passes. Otherwise it fails.
299
300 stdout_unlike
301
302 stdout_unlike($cmd, $unexp_regex, $name)
303
304 If the STDOUT of the command does not match the given regular
305 expression, this passes. Otherwise it fails.
306
307 stdout_cmp_ok
308
309 stdout_cmp_ok($cmd, $op, $operand, $name)
310
311 If the STDOUT of the command is compared with the given operand using
312 the given operator, and that operation returns true, this passes.
313 Otherwise it fails.
314
315 stdout_is_file
316
317 stdout_is_file($cmd, $exp_file, $name)
318
319 If the STDOUT of the command is equal (compared using "eq") to the
320 contents of the given file, then this passes. Otherwise it fails. Note
321 that this comparison is performed line by line, rather than slurping
322 the entire file.
323
324 Testing STDERR
325 Except where specified, the test routines below treat STDERR as a
326 single slurped string.
327
328 stderr_value
329
330 stderr_value($cmd)
331
332 Return the STDERR of the command. Useful for performing arbitrary tests
333 not covered by this module.
334
335 stderr_file
336
337 stderr_file($cmd)
338
339 Return the file name containing the STDERR of the command. Useful for
340 performing arbitrary tests not covered by this module.
341
342 stderr_is_eq
343
344 stderr_is_eq($cmd, $exp_string, $name)
345
346 If the STDERR of the command is equal (compared using "eq") to the
347 expected string, then this passes. Otherwise it fails.
348
349 stderr_isnt_eq
350
351 stderr_isnt_eq($cmd, $unexp_string, $name)
352
353 If the STDERR of the command is not equal (compared using "eq") to the
354 given string, this passes. Otherwise it fails.
355
356 stderr_is_num
357
358 stderr_is_num($cmd, $exp_num, $name)
359
360 If the STDERR of the command is equal (compared using "==") to the
361 expected number, then this passes. Otherwise it fails.
362
363 stderr_isnt_num
364
365 stderr_isnt_num($cmd, $unexp_num, $name)
366
367 If the STDERR of the command is not equal (compared using "==") to the
368 given number, this passes. Otherwise it fails.
369
370 stderr_like
371
372 stderr_like($cmd, $exp_regex, $name)
373
374 If the STDERR of the command matches the expected regular expression,
375 this passes. Otherwise it fails.
376
377 stderr_unlike
378
379 stderr_unlike($cmd, $unexp_regex, $name)
380
381 If the STDERR of the command does not match the given regular
382 expression, this passes. Otherwise it fails.
383
384 stderr_cmp_ok
385
386 stderr_cmp_ok($cmd, $op, $operand, $name)
387
388 If the STDERR of the command is compared with the given operand using
389 the given operator, and that operation returns true, this passes.
390 Otherwise it fails.
391
392 stderr_is_file
393
394 stderr_is_file($cmd, $exp_file, $name)
395
396 If the STDERR of the command is equal (compared using "eq") to the
397 contents of the given file, then this passes. Otherwise it fails. Note
398 that this comparison is performed line by line, rather than slurping
399 the entire file.
400
402 Daniel B. Boorstein, "<danboo at cpan.org>"
403
405 Please report any bugs or feature requests to "bug-test-command at
406 rt.cpan.org", or through the web interface at
407 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Command>. I will
408 be notified, and then you'll automatically be notified of progress on
409 your bug as I make changes.
410
412 You can find documentation for this module with the perldoc command.
413
414 perldoc Test::Command
415
416 You can also look for information at:
417
418 · AnnoCPAN: Annotated CPAN documentation
419
420 <http://annocpan.org/dist/Test-Command>
421
422 · CPAN Ratings
423
424 <http://cpanratings.perl.org/d/Test-Command>
425
426 · RT: CPAN's request tracker
427
428 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Command>
429
430 · Search CPAN
431
432 <http://search.cpan.org/dist/Test-Command>
433
435 Test::Builder by Michael Schwern allowed me to focus on the specifics
436 related to testing system commands by making it easy to produce proper
437 test output.
438
440 Copyright 2007 Daniel B. Boorstein, all rights reserved.
441
442 This program is free software; you can redistribute it and/or modify it
443 under the same terms as Perl itself.
444
446 · create a tool that produces test scripts given a list of commands to
447 run
448
449 · optionally save the temp files with STDOUT and STDERR for user
450 debugging
451
452 · if user defines all options and sample arguments to basic command
453
454 · create tool to enumerate all possible means of calling program
455
456 · allow testing with randomized/permuted/collapsed opts and args
457
458 · potential test functions:
459
460 · time_lt($cmd, $seconds)
461
462 · time_gt($cmd, $seconds)
463
464 · stdout_line_custom($cmd, \&code)
465
466 · stderr_line_custom($cmd, \&code)
467
469 Test::Builder provides the testing methods used in this module.
470
471 Test::Builder::Module is the superclass of this module.
472
473
474
475perl v5.32.0 2020-07-28 Test::Command(3)