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.08
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

DESCRIPTION

65       "Test::Command" intends to bridge the gap between the well tested
66       functions and objects you choose and their usage in your programs. By
67       examining the exit status, terminating signal, STDOUT and STDERR of
68       your program you can determine if it is behaving as expected.
69
70       This includes testing the various combinations and permutations of
71       options and arguments as well as the interactions between the various
72       functions and objects that make up your program.
73
74       The various test functions below can accept either a command string or
75       an array reference for the first argument. If the command is expressed
76       as a string it is passed to "system" as is. If the command is expressed
77       as an array reference it is dereferenced and passed to "system" as a
78       list. See '"perldoc -f system"' for how these may differ.
79
80       The final argument for the test functions, $name, is optional. By
81       default the $name is a concatenation of the test function name, the
82       command string and the expected value. This construction is generally
83       sufficient for identifying a failing test, but you may always specify
84       your own $name if desired.
85
86       Any of the test functions can be used as instance methods on a
87       "Test::Command" object. This is done by dropping the initial $cmd
88       argument and instead using arrow notation.
89
90       All of the following "exit_is_num" calls are equivalent.
91
92          exit_is_num('true', 0);
93          exit_is_num('true', 0, 'exit_is_num: true, 0');
94          exit_is_num(['true'], 0);
95          exit_is_num(['true'], 0, 'exit_is_num: true, 0');
96
97          my $cmd = Test::Command->new( cmd => 'true' );
98
99          exit_is_num($cmd, 0);
100          exit_is_num($cmd, 0, 'exit_is_num: true, 0');
101          $cmd->exit_is_num(0);
102          $cmd->exit_is_num(0, 'exit_is_num: true, 0');
103
104          $cmd = Test::Command->new( cmd => ['true'] );
105
106          exit_is_num($cmd, 0);
107          exit_is_num($cmd, 0, 'exit_is_num: true, 0');
108          $cmd->exit_is_num(0);
109          $cmd->exit_is_num(0, 'exit_is_num: true, 0');
110

EXPORT

112       All of the test functions mentioned below are exported by default.
113

METHODS

115   new
116          my $test_cmd_obj = Test::Command->new( cmd => $cmd )
117
118       This constructor creates and returns a "Test::Command" object. Use this
119       to test multiple aspects of a single command execution while avoiding
120       repeatedly running commands which are slow or resource intensive.
121
122       The "cmd" parameter can accept either a string or an array reference
123       for its value. The value is dereferenced if necessary and passed
124       directly to the "system" builtin.
125
126   run
127          $test_cmd_obj->run;
128
129       This instance method forces the execution of the command specified by
130       the invocant.
131
132       You only need to call this when you wish to re-run a command since the
133       first test method invoked will lazily execute the command if necessary.
134       However, if the state of your inputs has changed and you wish to re-run
135       the command, you may do so by invoking this method at any point between
136       your tests.
137

FUNCTIONS

139   Testing Exit Status
140       The test routines below compare against the exit status of the executed
141       command right shifted by 8 (that is, "$? >> 8").
142
143       exit_is_num
144
145          exit_is_num($cmd, $exp_num, $name)
146
147       If the exit status of the command is numerically equal to the expected
148       number, this passes. Otherwise it fails.
149
150       exit_isnt_num
151
152          exit_isnt_num($cmd, $unexp_num, $name)
153
154       If the exit status of the command is not numerically equal to the given
155       number, this passes. Otherwise it fails.
156
157       exit_cmp_ok
158
159          exit_cmp_ok($cmd, $op, $operand, $name)
160
161       If the exit status of the command is compared with the given operand
162       using the given operator, and that operation returns true, this passes.
163       Otherwise it fails.
164
165       exit_is_defined
166
167          exit_is_defined($cmd, $name)
168
169       If the exit status of the command is defined, this passes. Otherwise it
170       fails. A defined exit status indicates that the command exited normally
171       by calling exit() or running off the end of the program.
172
173       exit_is_undef
174
175          exit_is_undef($cmd, $name)
176
177       If the exit status of the command is not defined, this passes.
178       Otherwise it fails. An undefined exit status indicates that the command
179       likely exited due to a signal.
180
181   Testing Terminating Signal
182       The test routines below compare against the lower 8 bits of the exit
183       status of the executed command.
184
185       signal_is_num
186
187          signal_is_num($cmd, $exp_num, $name)
188
189       If the terminating signal of the command is numerically equal to the
190       expected number, this passes. Otherwise it fails.
191
192       signal_isnt_num
193
194          signal_isnt_num($cmd, $unexp_num, $name)
195
196       If the terminating signal of the command is not numerically equal to
197       the given number, this passes. Otherwise it fails.
198
199       signal_cmp_ok
200
201          signal_cmp_ok($cmd, $op, $operand, $name)
202
203       If the terminating signal of the command is compared with the given
204       operand using the given operator, and that operation returns true, this
205       passes. Otherwise it fails.
206
207       signal_is_defined
208
209          signal_is_defined($cmd, $name)
210
211       If the terminating signal of the command is defined, this passes.
212       Otherwise it fails. A defined signal indicates that the command likely
213       exited due to a signal.
214
215       signal_is_undef
216
217          signal_is_undef($cmd, $name)
218
219       If the terminating signal of the command is not defined, this passes.
220       Otherwise it fails. An undefined signal indicates that the command
221       exited normally by calling exit() or running off the end of the
222       program.
223
224   Testing STDOUT
225       Except where specified, the test routines below treat STDOUT as a
226       single slurped string.
227
228       stdout_is_eq
229
230          stdout_is_eq($cmd, $exp_string, $name)
231
232       If the STDOUT of the command is equal (compared using "eq") to the
233       expected string, then this passes. Otherwise it fails.
234
235       stdout_isnt_eq
236
237          stdout_isnt_eq($cmd, $unexp_string, $name)
238
239       If the STDOUT of the command is not equal (compared using "eq") to the
240       given string, this passes. Otherwise it fails.
241
242       stdout_is_num
243
244          stdout_is_num($cmd, $exp_num, $name)
245
246       If the STDOUT of the command is equal (compared using "==") to the
247       expected number, then this passes. Otherwise it fails.
248
249       stdout_isnt_num
250
251          stdout_isnt_num($cmd, $unexp_num, $name)
252
253       If the STDOUT of the command is not equal (compared using "==") to the
254       given number, this passes. Otherwise it fails.
255
256       stdout_like
257
258          stdout_like($cmd, $exp_regex, $name)
259
260       If the STDOUT of the command matches the expected regular expression,
261       this passes. Otherwise it fails.
262
263       stdout_unlike
264
265          stdout_unlike($cmd, $unexp_regex, $name)
266
267       If the STDOUT of the command does not match the given regular
268       expression, this passes. Otherwise it fails.
269
270       stdout_cmp_ok
271
272          stdout_cmp_ok($cmd, $op, $operand, $name)
273
274       If the STDOUT of the command is compared with the given operand using
275       the given operator, and that operation returns true, this passes.
276       Otherwise it fails.
277
278       stdout_is_file
279
280          stdout_is_file($cmd, $exp_file, $name)
281
282       If the STDOUT of the command is equal (compared using "eq") to the
283       contents of the given file, then this passes. Otherwise it fails. Note
284       that this comparison is performed line by line, rather than slurping
285       the entire file.
286
287   Testing STDERR
288       Except where specified, the test routines below treat STDERR as a
289       single slurped string.
290
291       stderr_is_eq
292
293          stderr_is_eq($cmd, $exp_string, $name)
294
295       If the STDERR of the command is equal (compared using "eq") to the
296       expected string, then this passes. Otherwise it fails.
297
298       stderr_isnt_eq
299
300          stderr_isnt_eq($cmd, $unexp_string, $name)
301
302       If the STDERR of the command is not equal (compared using "eq") to the
303       given string, this passes. Otherwise it fails.
304
305       stderr_is_num
306
307          stderr_is_num($cmd, $exp_num, $name)
308
309       If the STDERR of the command is equal (compared using "==") to the
310       expected number, then this passes. Otherwise it fails.
311
312       stderr_isnt_num
313
314          stderr_isnt_num($cmd, $unexp_num, $name)
315
316       If the STDERR of the command is not equal (compared using "==") to the
317       given number, this passes. Otherwise it fails.
318
319       stderr_like
320
321          stderr_like($cmd, $exp_regex, $name)
322
323       If the STDERR of the command matches the expected regular expression,
324       this passes. Otherwise it fails.
325
326       stderr_unlike
327
328          stderr_unlike($cmd, $unexp_regex, $name)
329
330       If the STDERR of the command does not match the given regular
331       expression, this passes. Otherwise it fails.
332
333       stderr_cmp_ok
334
335          stderr_cmp_ok($cmd, $op, $operand, $name)
336
337       If the STDERR of the command is compared with the given operand using
338       the given operator, and that operation returns true, this passes.
339       Otherwise it fails.
340
341       stderr_is_file
342
343          stderr_is_file($cmd, $exp_file, $name)
344
345       If the STDERR of the command is equal (compared using "eq") to the
346       contents of the given file, then this passes. Otherwise it fails. Note
347       that this comparison is performed line by line, rather than slurping
348       the entire file.
349

AUTHOR

351       Daniel B. Boorstein, "<danboo at cpan.org>"
352

BUGS

354       Please report any bugs or feature requests to "bug-test-command at
355       rt.cpan.org", or through the web interface at
356       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Command
357       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Command>.  I will
358       be notified, and then you'll automatically be notified of progress on
359       your bug as I make changes.
360

SUPPORT

362       You can find documentation for this module with the perldoc command.
363
364           perldoc Test::Command
365
366       You can also look for information at:
367
368       ·   AnnoCPAN: Annotated CPAN documentation
369
370           http://annocpan.org/dist/Test-Command
371           <http://annocpan.org/dist/Test-Command>
372
373       ·   CPAN Ratings
374
375           http://cpanratings.perl.org/d/Test-Command
376           <http://cpanratings.perl.org/d/Test-Command>
377
378       ·   RT: CPAN's request tracker
379
380           http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Command
381           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Command>
382
383       ·   Search CPAN
384
385           http://search.cpan.org/dist/Test-Command
386           <http://search.cpan.org/dist/Test-Command>
387

ACKNOWLEDGEMENTS

389       Test::Builder by Michael Schwern allowed me to focus on the specifics
390       related to testing system commands by making it easy to produce proper
391       test output.
392

COPYRIGHT & LICENSE

394       Copyright 2007 Daniel B. Boorstein, all rights reserved.
395
396       This program is free software; you can redistribute it and/or modify it
397       under the same terms as Perl itself.
398

DEVELOPMENT IDEAS

400       ·  create a tool that produces test scripts given a list of commands to
401          run
402
403       ·  optionally save the temp files with STDOUT and STDERR for user
404          debugging
405
406       ·  if user defines all options and sample arguments to basic command
407
408          ·  create tool to enumerate all possible means of calling program
409
410          ·  allow testing with randomized/permuted/collapsed opts and args
411
412       ·  potential test functions:
413
414          ·  time_lt($cmd, $seconds)
415
416          ·  time_gt($cmd, $seconds)
417
418          ·  stdout_line_custom($cmd, \&code)
419
420          ·  stderr_line_custom($cmd, \&code)
421