Test::Command(3pm)

1Test::Command(3)      User Contributed Perl Documentation     Test::Command(3)
2
3
4

NAME

6       Test::Command - Test routines for external commands
7

VERSION

9       Version 0.11
10

SYNOPSIS

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

DESCRIPTION

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

EXPORT

121       All of the test functions mentioned below are exported by default.
122

METHODS

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

FUNCTIONS

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

AUTHOR

402       Daniel B. Boorstein, "<danboo at cpan.org>"
403

BUGS

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

SUPPORT

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

ACKNOWLEDGEMENTS

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

COPYRIGHT & LICENSE

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

DEVELOPMENT IDEAS

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