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

NAME

6       Test::Cmd - Perl module for portable testing of commands and scripts
7

SYNOPSIS

9       An example using Test::More with this module to run a command and then
10       test the exit code, standard out, and standard error:
11
12         use Test::Cmd;
13         use Test::More tests => 3;
14
15         my $test = Test::Cmd->new( prog => 'outerr', workdir => '' );
16         $test->run();
17
18         is( $test->stdout, "out\n", 'standard out' );
19         is( $test->stderr, "err\n", 'standard error' );
20         is( $? >> 8,       1,       'exit status' );
21
22       Where "outerr" is the shell script:
23
24         $ cat outerr
25         #!/bin/sh
26         echo out
27         echo >&2 err
28         exit 1
29         $ chmod +x outerr
30
31       See below for other examples. Otherwise, the full list of available
32       methods is:
33
34         use Test::Cmd;
35
36         $test = Test::Cmd->new(prog => 'program_or_script_to_test',
37                               interpreter => 'script_interpreter',
38                               string => 'identifier_string',
39                               workdir => '',
40                               subdir => 'dir',
41                               match_sub => $code_ref,
42                               verbose => 1);
43
44         $test->verbose(1);
45
46         $test->prog('program_or_script_to_test');
47
48         $test->basename(@suffixlist);
49
50         $test->interpreter('script_interpreter');
51
52         $test->string('identifier string');
53
54         $test->workdir('prefix');
55
56         $test->workpath('subdir', 'file');
57
58         $test->subdir('subdir', ...);
59         $test->subdir(['sub', 'dir'], ...);
60
61         $test->write('file', <<'EOF');
62         contents of file
63         EOF
64         $test->write(['subdir', 'file'], <<'EOF');
65         contents of file
66         EOF
67
68         $test->read(\$contents, 'file');
69         $test->read(\@lines, 'file');
70         $test->read(\$contents, ['subdir', 'file']);
71         $test->read(\@lines, ['subdir', 'file']);
72
73         $test->writable('dir');
74         $test->writable('dir', $rwflag);
75         $test->writable('dir', $rwflag, \%errors);
76
77         $test->preserve(condition, ...);
78
79         $test->cleanup(condition);
80
81         $test->run(prog => 'program_or_script_to_test',
82                       interpreter => 'script_interpreter',
83                       chdir => 'dir', args => 'arguments', stdin => <<'EOF');
84         input to program
85         EOF
86
87         $test->pass(condition);
88         $test->pass(condition, \&func);
89
90         $test->fail(condition);
91         $test->fail(condition, \&func);
92         $test->fail(condition, \&func, $caller);
93
94         $test->no_result(condition);
95         $test->no_result(condition, \&func);
96         $test->no_result(condition, \&func, $caller);
97
98         $test->stdout;
99         $test->stdout($run_number);
100
101         $test->stderr;
102         $test->stderr($run_number);
103
104         $test->match(\@lines, \@matches);
105         $test->match($lines, $matches);
106
107         $test->match_exact(\@lines, \@matches);
108         $test->match_exact($lines, $matches);
109
110         $test->match_regex(\@lines, \@regexes);
111         $test->match_regex($lines, $regexes);
112
113         $test->diff_exact(\@lines, \@matches, \@output);
114         $test->diff_exact($lines, $matches, \@output);
115
116         $test->diff_regex(\@lines, \@regexes, \@output);
117         $test->diff_regex($lines, $regexes, \@output);
118
119         sub func {
120               my ($self, $lines, $matches) = @_;
121               # code to match $lines and $matches
122         }
123         $test->match_sub(\&func);
124         $test->match_sub(sub { code to match $_[1] and $_[2] });
125
126         $test->here;
127

DESCRIPTION

129       The "Test::Cmd" module provides a low-level framework for portable
130       automated testing of executable commands and scripts (in any language,
131       not just Perl), especially commands and scripts that interact with the
132       file system.
133
134       The "Test::Cmd" module makes no assumptions about what constitutes a
135       successful or failed test.  Attempting to read a file that doesn't
136       exist, for example, may or may not be an error, depending on the
137       software being tested.
138
139       Consequently, no "Test::Cmd" methods (including the new() method) exit,
140       die or throw any other sorts of exceptions (but they all do return
141       useful error indications).  Exceptions or other error status should be
142       handled by a higher layer: a subclass of Test::Cmd, or another testing
143       framework such as the Test or Test::Simple Perl modules, or by the test
144       itself.
145
146       (That said, see the Test::Cmd::Common module if you want a similar
147       module that provides exception handling, either to use directly in your
148       own tests, or as an example of how to use "Test::Cmd".)
149
150       In addition to running tests and evaluating conditions, the "Test::Cmd"
151       module manages and cleans up one or more temporary workspace
152       directories, and provides methods for creating files and directories in
153       those workspace directories from in-line data (that is, here-
154       documents), allowing tests to be completely self-contained.  When used
155       in conjunction with another testing framework, the "Test::Cmd" module
156       can function as a fixture (common startup code for multiple tests) for
157       simple management of command execution and temporary workspaces.
158
159       The "Test::Cmd" module inherits File::Spec methods
160       (file_name_is_absolute(), catfile(), etc.) to support writing tests
161       portably across a variety of operating and file systems.
162
163       A "Test::Cmd" environment object is created via the usual invocation:
164
165           $test = Test::Cmd->new();
166
167       Arguments to the "Test::Cmd::new" method are keyword-value pairs that
168       may be used to initialize the object, typically by invoking the same-
169       named method as the keyword.
170

TESTING FRAMEWORKS

172       As mentioned, because the "Test::Cmd" module makes no assumptions about
173       what constitutes success or failure of a test, it can be used to
174       provide temporary workspaces, other file system interaction, or command
175       execution for a variety of testing frameworks.  This section describes
176       how to use the "Test::Cmd" with several different higher-layer testing
177       frameworks.
178
179       Note that you should not intermix multiple testing frameworks in a
180       single testing script.
181
182   "Test::Harness"
183       The "Test::Cmd" module may be used in tests that print results in a
184       format suitable for the standard Perl Test::Harness module:
185
186           use Test::Cmd;
187
188           print "1..5\n";
189
190           $test = Test::Cmd->new(prog => 'test_program', workdir => '');
191           if ($test) { print "ok 1\n"; } else { print "not ok 1\n"; }
192
193           $input = <<_EOF;
194           test_program should process this input
195           and exit successfully (status 0).
196           _EOF_
197
198           $wrote_file = $test->write('input_file', $input);
199           if ($wrote_file) { print "ok 2\n"; } else { print "not ok 2\n"; }
200
201           $test->run(args => '-x input_file');
202           if ($? == 0) { print "ok 3\n"; } else { print "not ok 3\n"; }
203
204           $wrote_file = $test->write('input_file', $input);
205           if ($wrote_file) { print "ok 4\n"; } else { print "not ok 4\n"; }
206
207           $test->run(args => '-y input_file');
208           if ($? == 0) { print "ok 5\n"; } else { print "not ok 5\n"; }
209
210       Several other Perl modules simplify the use of Test::Harness by
211       eliminating the need to hand-code the "print" statements and test
212       numbers.  The Test module, the Test::Simple module, and the Test::More
213       module all export an ok() subroutine to test conditions.  Here is how
214       the above example would look rewritten to use Test::Simple:
215
216           use Test::Simple tests => 5;
217           use Test::Cmd;
218
219           $test = Test::Cmd->new(prog => 'test_program', workdir => '');
220           ok($test, "creating Test::Cmd object");
221
222           $input = <<_EOF;
223           test_program should process this input
224           and exit successfully (status 0).
225           _EOF_
226
227           $wrote_file = $test->write('input_file', $input);
228           ok($wrote_file, "writing input_file");
229
230           $test->run(args => '-x input_file');
231           ok($? == 0, "executing test_program -x input_file");
232
233           $wrote_file = $test->write('input_file', $input);
234           ok($wrote_file, "writing input_file");
235
236           $test->run(args => '-y input_file');
237           ok($? == 0, "executing test_program -y input_file");
238
239   "Test::Unit"
240       The Perl Test::Unit package provides a procedural testing interface
241       modeled after a testing framework widely used in the eXtreme
242       Programming development methodology.  The "Test::Cmd" module can
243       function as part of a Test::Unit fixture that can set up workspaces as
244       needed for a set of tests.  This avoids having to repeat code to re-
245       initialize an input file multiple times:
246
247           use Test::Unit;
248           use Test::Cmd;
249
250           my $test;
251
252           $input = <<'EOF';
253           test_program should process this input
254           and exit successfully (status 0).
255           EOF
256
257           sub set_up {
258               $test = Test::Cmd->new(prog => 'test_program', workdir => '');
259               $test->write('input_file', $input);
260           }
261
262           sub test_x {
263               my $result = $test->run(args => '-x input_file');
264               assert($result == 0, "failed test_x\n");
265           }
266
267           sub test_y {
268               my $result = $test->run(args => '-y input_file');
269               assert($result == 0, "failed test_y\n");
270           }
271
272           create_suite();
273           run_suite;
274
275       Note that, because the "Test::Cmd" module takes care of cleaning up
276       temporary workspaces on exit, there is no need to remove explicitly the
277       workspace in a "tear_down" subroutine.  (There may, of course, be other
278       things in the test that need a "tear_down" subroutine.)
279
280   Aegis
281       Alternatively, the "Test::Cmd" module provides pass(), fail(), and
282       no_result() methods that can be used to provide an appropriate exit
283       status and simple printed indication for a test.  These methods
284       terminate the test immediately, reporting "PASSED", "FAILED", or "NO
285       RESULT" respectively, and exiting with status 0 (success), 1 or 2
286       respectively.
287
288       The separate fail() and no_result() methods allow for a distinction
289       between an actual failed test and a test that could not be properly
290       evaluated because of an external condition (such as a full file system
291       or incorrect permissions).
292
293       The exit status values happen to match the requirements of the Aegis
294       change management system, and the printed strings are based on existing
295       Aegis conventions.  They are not really Aegis-specific, however, and
296       provide a simple, useful starting point if you don't already have
297       another testing framework:
298
299           use Test::Cmd;
300
301           $test = Test::Cmd->new(prog => 'test_program', workdir => '');
302           Test::Cmd->no_result(! $test);
303
304           $input = <<EOF;
305           test_program should process this input
306           and exit successfully (status 0).
307           EOF
308
309           $wrote_file = $test->write('input_file', $input);
310           $test->no_result(! $wrote_file);
311
312           $test->run(args => '-x input_file');
313           $test->fail($? != 0);
314
315           $wrote_file = $test->write('input_file', $input);
316           $test->no_result(! $wrote_file);
317
318           $test->run(args => '-y input_file');
319           $test->fail($? != 0);
320
321           $test->pass;
322
323       Note that the separate Test::Cmd::Common wrapper module can simplify
324       the above example even further by taking care of common exception
325       handling cases within the testing object itself.
326
327           use Test::Cmd::Common;
328
329           $test = Test::Cmd::Common->new(prog => 'test_program', workdir => '');
330
331           $input = <<EOF;
332           test_program should process this input
333           and exit successfully (status 0).
334           EOF
335
336           $wrote_file = $test->write('input_file', $input);
337
338           $test->run(args => '-x input_file');
339
340           $wrote_file = $test->write('input_file', $input);
341
342           $test->run(args => '-y input_file');
343
344           $test->pass;
345
346       See the Test::Cmd::Common module for details.
347

METHODS

349       Methods supported by the "Test::Cmd" module include:
350
351       "new"
352           Create a new "Test::Cmd" environment.  Arguments with which to
353           initialize the environment are passed in as keyword-value pairs.
354           Fails if a specified temporary working directory or subdirectory
355           cannot be created.  Does NOT die or exit on failure, but returns
356           "undef" if the test environment object cannot be created.
357
358       "verbose"
359           Sets the verbose level for the environment object to the specified
360           value.
361
362       "prog"
363           Specifies the executable program or script to be tested.  Returns
364           the absolute path name of the current program or script.
365
366       "basename"
367           Returns the basename of the current program or script.  Any
368           specified arguments are a list of file suffixes that may be
369           stripped from the basename.
370
371       "interpreter"
372           Specifies the program to be used to interpret "prog" as a script.
373           Returns the current value of "interpreter".
374
375       "string"
376           Specifies an identifier string for the functionality being tested
377           to be printed on failure or no result.
378
379       "workdir"
380           When an argument is specified, creates a temporary working
381           directory with the specified name.  If the argument is a NULL
382           string (''), the directory is named "testcmd" by default, followed
383           by the unique ID of the executing process.
384
385           Returns the absolute pathname to the temporary working directory,
386           or FALSE if the directory could not be created.
387
388       "workpath"
389           Returns the absolute path name to a subdirectory or file under the
390           current temporary working directory by concatenating the temporary
391           working directory name with the specified arguments.
392
393       "subdir"
394           Creates new subdirectories under the temporary working dir, one for
395           each argument.  An argument may be an array reference, in which
396           case the array elements are concatenated together using the
397           "File::Spec-&"catfile> method.  Subdirectories multiple levels deep
398           must be created via a separate argument for each level:
399
400               $test->subdir('sub', ['sub', 'dir'], [qw(sub dir ectory)]);
401
402           Returns the number of subdirectories actually created.
403
404       "write"
405           Writes the specified text (second argument) to the specified file
406           name (first argument).  The file name may be an array reference, in
407           which case all the array elements except the last are subdirectory
408           names to be concatenated together.  The file is created under the
409           temporary working directory.  Any subdirectories in the path must
410           already exist.
411
412       "read"
413           Reads the contents of the specified file name (second argument)
414           into the scalar or array referred to by the first argument.  The
415           file name may be an array reference, in which case all the array
416           elements except the last are subdirectory names to be concatenated
417           together.  The file is assumed to be under the temporary working
418           directory unless it is an absolute path name.
419
420           Returns TRUE on successfully opening and reading the file, FALSE
421           otherwise.
422
423       "writable"
424           Makes every file and directory within the specified directory tree
425           writable ("rwflag" == TRUE) or not writable ("rwflag" == FALSE).
426           The default is to make the directory tree writable.  Optionally
427           fills in the supplied hash reference with a hash of path names that
428           could not have their permissions set appropriately, with the reason
429           why each could not be set.
430
431       "preserve"
432           Arranges for the temporary working directories for the specified
433           "Test::Cmd" environment to be preserved for one or more conditions.
434           If no conditions are specified, arranges for the temporary working
435           directories to be preserved for all conditions.
436
437       "cleanup"
438           Removes any temporary working directories for the specified
439           "Test::Cmd" environment.  If the environment variable "PRESERVE"
440           was set when the "Test::Cmd" module was loaded, temporary working
441           directories are not removed.  If any of the environment variables
442           "PRESERVE_PASS", "PRESERVE_FAIL", or "PRESERVE_NO_RESULT" were set
443           when the "Test::Cmd" module was loaded, then temporary working
444           directories are not removed if the test passed, failed, or had no
445           result, respectively.  Temporary working directories are also
446           preserved for conditions specified via the "preserve" method.
447
448           Typically, this method is not called directly, but is used when the
449           script exits to clean up temporary working directories as
450           appropriate for the exit status.
451
452       "run"
453           Runs a test of the program or script for the test environment.
454           Standard output and error output are saved for future retrieval via
455           the "stdout" and "stderr" methods.
456
457           Arguments are supplied as keyword-value pairs:
458
459           "args"
460               Specifies the command-line arguments to be supplied to the
461               program or script under test for this run:
462
463                       $test->run(args => 'arg1 arg2');
464
465           "chdir"
466               Changes directory to the path specified as the value argument:
467
468                       $test->run(chdir => 'xyzzy');
469
470               If the specified path is not an absolute path name (begins with
471               '/' on Unix systems), then the subdirectory is relative to the
472               temporary working directory for the environment
473               ("$test-&"workdir>).  Note that, by default, the "Test::Cmd"
474               module does NOT chdir to the temporary working directory, so to
475               execute the test under the temporary working directory, you
476               must specify an explicit "chdir" to the current directory:
477
478                       $test->run(chdir => '.');               # Unix-specific
479
480                       $test->run(chdir => $test->curdir);     # portable
481
482           "interpreter"
483               Specifies the program to be used to interpret "prog" as a
484               script, for this run only.  This does not change the
485               "$test-&"interpreter> value of the test environment.
486
487           "prog"
488               Specifies the executable program or script to be run, for this
489               run only.  This does not change the "$test-&"prog> value of the
490               test environment.
491
492           "stdin"
493               Pipes the specified value (string or array ref) to the program
494               or script under test for this run:
495
496                       $test->run(stdin => <<_EOF_);
497                       input to the program under test
498                       _EOF_
499
500           Returns the exit status of the program or script.
501
502       "pass"
503           Exits the test successfully.  Reports "PASSED" on the error output
504           and exits with a status of 0.  If a condition is supplied, only
505           exits the test if the condition evaluates TRUE.  If a function
506           reference is supplied, executes the function before reporting and
507           exiting.
508
509       "fail"
510           Exits the test unsuccessfully.  Reports "FAILED test of {string} at
511           line {line} of {file}." on the error output and exits with a status
512           of 1.  If a condition is supplied, only exits the test if the
513           condition evaluates TRUE.  If a function reference is supplied,
514           executes the function before reporting and exiting.  If a caller
515           level is supplied, prints a simple calling trace N levels deep as
516           part of reporting the failure.
517
518       "no_result"
519           Exits the test with an indeterminate result (the test could not be
520           performed due to external conditions such as, for example, a full
521           file system).  Reports "NO RESULT for test of {string} at line
522           {line} of {file}." on the error output and exits with a status of
523           2.  If a condition is supplied, only exits the test if the
524           condition evaluates TRUE.  If a function reference is supplied,
525           executes the function before reporting and exiting.  If a caller
526           level is supplied, prints a simple calling trace N levels deep as
527           part of reporting the failure.
528
529       "stdout"
530           Returns the standard output from the specified run number.  If
531           there is no specified run number, then returns the standard output
532           of the last run.  Returns the standard output as either a scalar or
533           an array of output lines, as appropriate for the calling context.
534           Returns "undef" if there has been no test run.
535
536       "stderr"
537           Returns the error output from the specified run number.  If there
538           is no specified run number, then returns the error output of the
539           last run.  Returns the error output as either a scalar or an array
540           of output lines, as apporpriate for the calling context.  Returns
541           "undef" if there has been no test run.
542
543       "match"
544           Matches one or more input lines against an equal number of expected
545           lines using the currently-registered line-matching function.  The
546           default line-matching function is the "match_regex" method, which
547           means that the default is to match lines against regular
548           expressions.
549
550       "match_exact"
551           Compares two arrays of lines for exact matches.  The arguments are
552           passed in as either scalars, in which case each is split on newline
553           boundaries, or as array references.  An unequal number of lines in
554           the two arrays fails immediately and returns FALSE before any
555           comparisons are performed.
556
557           Returns TRUE if each line matched its corresponding line in the
558           other array, FALSE otherwise.
559
560       "match_regex"
561           Matches one or more input lines against an equal number of regular
562           expressions.  The arguments are passed in as either scalars, in
563           which case each is split on newline boundaries, or as array
564           references.  Trailing newlines are stripped from each line and
565           regular expression.  An unequal number of lines and regular
566           expressions fails immediately and returns FALSE before any
567           comparisons are performed.  Comparison is performed for each entire
568           line, that is, with each regular expression anchored at both the
569           start of line (^) and end of line ($).
570
571           Returns TRUE if each line matched each regular expression, FALSE
572           otherwise.
573
574       "diff_exact"
575           Diffs two arrays of lines in a manner similar to the UNIX diff(1)
576           utility.
577
578           If the Algorithm::DiffOld package is installed on the local system,
579           output describing the differences between the input lines and the
580           matching lines, in diff(1) format, is saved to the $output array
581           reference.  In the diff output, the expected output lines are
582           considered the "old" (left-hand) file, and the actual output is
583           considered the "new" (right-hand) file.
584
585           If the Algorithm::DiffOld package is not installed on the local
586           system, the Expected and Actual contents are saved as-is to the
587           $output array reference.
588
589           The "lines" and "matches" arguments are passed in as either
590           scalars, in which case each is split on newline boundaries, or as
591           array references.  Trailing newlines are stripped from each line
592           and regular expression.
593
594           Returns TRUE if each line matched its corresponding line in the
595           expected matches, FALSE otherwise, in order to conform to the
596           conventions of the "match" method.
597
598           Typical invocation:
599
600                   if (! $test->diff_exact($test->stdout,
601                                           \@expected_lines,
602                                           \@diff)) {
603                           print @diff;
604                   }
605
606       "diff_regex"
607           Diffs one or more input lines against one or more regular
608           expressions in a manner similar to the UNIX diff(1) utility.
609
610           If the Algorithm::DiffOld package is installed on the local system,
611           output describing the differences between the input lines and the
612           matching lines, in diff(1) format, is saved to the $output array
613           reference.  In the diff output, the expected output lines are
614           considered the "old" (left-hand) file, and the actual output is
615           considered the "new" (right-hand) file.
616
617           If the Algorithm::DiffOld package is not installed on the local
618           system, the Expected and Actual contents are saved as-is to the
619           $output array reference.
620
621           The "lines" and "regexes" arguments are passed in as either
622           scalars, in which case each is split on newline boundaries, or as
623           array references.  Trailing newlines are stripped from each line
624           and regular expression.  Comparison is performed for each entire
625           line, that is, with each regular expression anchored at both the
626           start of line (^) and end of line ($).
627
628           Returns TRUE if each line matched each regular expression, FALSE
629           otherwise, in order to conform to the conventions of the "match"
630           method.
631
632           Typical invocation:
633
634                   if (! $test->diff_regex($test->stdout,
635                                           \@expected_lines,
636                                           \@diff)) {
637                           print @diff;
638                   }
639
640       "match_sub"
641           Registers the specified code reference as the line-matching
642           function to be called by the "match" method.  This can be a user-
643           supplied subroutine, or the "match_exact", "match_regex",
644           "diff_exact", or "diff_regex" methods supplied by the "Test::Cmd"
645           module:
646
647                   $test->match_sub(\&Test::Cmd::match_exact);
648
649                   $test->match_sub(\&Test::Cmd::match_regex);
650
651                   $test->match_sub(\&Test::Cmd::diff_exact);
652
653                   $test->match_sub(\&Test::Cmd::diff_regex);
654
655           The "match_exact", "match_regex", "diff_exact" and "diff_regex"
656           subroutine names are exportable from the "Test::Cmd" module, and
657           may be specified at object initialization:
658
659                   use Test::Cmd qw(match_exact match_regex diff_exact diff_regex);
660                   $test_exact = Test::Cmd->new(match_sub => \&match_exact);
661                   $test_regex = Test::Cmd->new(match_sub => \&match_regex);
662                   $test_exact = Test::Cmd->new(match_sub => \&diff_exact);
663                   $test_regex = Test::Cmd->new(match_sub => \&diff_regex);
664
665       "here"
666           Returns the absolute path name of the current working directory.
667           (This is essentially the same as the "Cwd::cwd" method, except that
668           the "Test::Cmd::here" method preserves the directory separators
669           exactly as returned by the underlying operating-system-dependent
670           method.  The "Cwd::cwd" method canonicalizes all directory
671           separators to '/', which makes for consistent path name
672           representations within Perl, but may mess up another program or
673           script to which you try to pass the path name.)
674

ENVIRONMENT

676       Several environment variables affect the default values in a newly
677       created "Test::Cmd" environment object.  These environment variables
678       must be set when the module is loaded, not when the object is created.
679
680       "PRESERVE"
681           If set to a true value, all temporary working directories will be
682           preserved on exit, regardless of success or failure of the test.
683           The full path names of all temporary working directories will be
684           reported on error output.
685
686       "PRESERVE_FAIL"
687           If set to a true value, all temporary working directories will be
688           preserved on exit from a failed test.  The full path names of all
689           temporary working directories will be reported on error output.
690
691       "PRESERVE_NO_RESULT"
692           If set to a true value, all temporary working directories will be
693           preserved on exit from a test for which there is no result.  The
694           full path names of all temporary working directories will be
695           reported on error output.
696
697       "PRESERVE_PASS"
698           If set to a true value, all temporary working directories will be
699           preserved on exit from a successful test.  The full path names of
700           all temporary working directories will be reported on error output.
701
702       "VERBOSE"
703           When set to a true value, enables verbose reporting of various
704           internal things (path names, exact command line being executed,
705           etc.).
706

PORTABLE TESTS

708       Although the "Test::Cmd" module is intended to make it easier to write
709       portable tests for portable utilities that interact with file systems,
710       it is still very easy to write non-portable tests if you're not
711       careful.
712
713       The best and most comprehensive set of portability guidelines is the
714       standard "Writing portable Perl" document at:
715
716               http://www.perl.com/pub/doc/manual/html/pod/perlport.html
717
718       To reiterate one important point from the "WpP" document:  Not all Perl
719       programs have to be portable.  If the program or script you're testing
720       is UNIX-specific, you can (and should) use the "Test::Cmd" module to
721       write UNIX-specific tests.
722
723       That having been said, here are some hints that may help keep your
724       tests portable, if that's a requirement.
725
726       Use the "Test::Cmd-&"here> method for current directory path.
727           The normal Perl way to fetch the current working directory is to
728           use the "Cwd::cwd" method.  Unfortunately, the "Cwd::cwd" method
729           canonicalizes the path name it returns, changing the native
730           directory separators into the forward slashes favored by Perl and
731           UNIX.  For most Perl scripts, this makes a great deal of sense and
732           keeps code uncluttered.
733
734           Passing in a file name that has had its directory separators
735           altered, however, may confuse the command or script under test, or
736           make it difficult to compare output from the command or script with
737           an expected result.  The "Test::Cmd::here" method returns the
738           absolute path name of the current working directory, like
739           "Cwd::cwd", but does not manipulate the returned path in any way.
740
741       Use "File::Spec" methods for manipulating path names.
742           The File::Spec module provides a system-independent interface for
743           manipulating path names.  Because the "Test::Cmd" class is a sub-
744           class of the File::Spec class, you can use these methods directly
745           as follows:
746
747                   if (! Test::Cmd->file_name_is_absolute($prog)) {
748                           my $prog = Test::Cmd->catfile(Test::Cmd->here, $prog);
749                   }
750
751           For details about the available methods and their use, see the
752           documentation for the File::Spec module and its sub-modules,
753           especially the File::Spec::Unix modules.
754
755       Use "Config" for file-name suffixes, where possible.
756           The standard Config module provides values that reflect the file-
757           name suffixes on the system for which the Perl executable was
758           built.  This provides convenient portability for situations where a
759           file name may have different extensions on different systems:
760
761                   $foo_exe = "foo$Config{_exe}";
762                   ok(-f $foo_exe);
763
764           (Unfortunately, there is no existing $Config value that specifies
765           the suffix for a directly-executable Perl script.)
766
767       Avoid generating executable programs or scripts.
768           How to make a file or script executable varies widely from system
769           to system, some systems using file name extensions to indicate
770           executability, others using a file permission bit.  The differences
771           are complicated to accommodate in a portable test script.  The
772           easiest way to deal with this complexity is to avoid it if you can.
773
774           If your test somehow requires executing a script that you generate
775           from the test itself, the best way is to generate the script in
776           Perl and then explicitly feed it to the Perl executable on the
777           local system.  To be maximally portable, use the $^X variable
778           instead of hard-coding "perl" into the string you execute:
779
780                   $line = "This is output from the generated perl script.";
781                   $test->write('script', <<EOF);
782                   print STDOUT "$line\\n";
783                   EOF
784                   $output = `$^X script`;
785                   ok($output eq "$line\n");
786
787           This completely avoids having to make the "script" file itself
788           executable.  (Since you're writing your test in Perl, it's safe to
789           assume that Perl itself is executable.)
790
791           If you must generate a directly-executable script, then use the
792           $Config{'startperl'} variable at the start of the script to
793           generate the appropriate magic that will execute it as a Perl
794           script:
795
796                   use Config;
797                   $line = "This is output from the generated perl script.";
798                   $test->write('script', <<EOF);
799                   $Config{'startperl'};
800                   print STDOUT "$line\\n";
801                   EOF
802                   chdir($test->workdir);
803                   chmod(0755, 'script');  # POSIX-SPECIFIC
804                   $output = `script`;
805                   ok($output eq "$line\n");
806
807       Addtional hints on writing portable tests are welcome.
808

SEE ALSO

810       perl(1), Algorithm::DiffOld, File::Find, File::Spec, Test,
811       Test::Cmd::Common, Test::Harness, Test::More, Test::Simple, Test::Unit.
812
813       Alternative command-testing modules include:
814
815       Test::Exit, Test::Output, or using Capture::Tiny with one of the above
816       test modules, for example Test::More.
817
818       A rudimentary page for the "Test::Cmd" module is available at:
819
820               http://www.baldmt.com/Test-Cmd/
821
822       The most involved example of using the "Test::Cmd" package to test a
823       real-world application is the "cons-test" testing suite for the Cons
824       software construction utility.  The suite uses a sub-class of
825       Test::Cmd::Common (which in turn is a sub-class of "Test::Cmd") to
826       provide common, application-specific infrastructure across a large
827       number of end-to-end application tests.  The suite, and other
828       information about Cons, is available at:
829
830               http://www.dsmit.com/cons
831

REPOSITORY

833       <https://github.com/neilb/Test-Cmd>
834

AUTHORS

836       Steven Knight, knight@baldmt.com
837
838       This module is now being maintained by Neil Bowers <neilb@cpan.org>.
839
841       Copyright 1999-2001 Steven Knight.  All rights reserved.  This program
842       is free software; you can redistribute it and/or modify it under the
843       same terms as Perl itself.
844

ACKNOWLEDGEMENTS

846       Thanks to Greg Spencer for the inspiration to create this package and
847       the initial draft of its implementation as a specific testing package
848       for the Cons software construction utility.  Information about Cons is
849       available at:
850
851               http://www.dsmit.com/cons/
852
853       The general idea of managing temporary working directories in this way,
854       as well as the test reporting of the "pass", "fail" and "no_result"
855       methods, come from the testing framework invented by Peter Miller for
856       his Aegis project change supervisor.  Aegis is an excellent bit of work
857       which integrates creation and execution of regression tests into the
858       software development process.  Information about Aegis is available at:
859
860               http://www.tip.net.au/~millerp/aegis.html
861
862       Thanks to Michael Schwern for all of the thoughtful work he's put into
863       Perl's standard testing methodology, including the Test::Simple and
864       Test::More modules, and enhancement and maintenance of the Test and
865       Test::Harness modules.  Thanks also to Christian Lemburg for the
866       impressively complete Test::Unit framework of modules.  Ideas from both
867       have helped keep "Test::Cmd" flexible enough to be useful in multiple
868       testing frameworks.
869
870
871
872perl v5.36.0                      2023-01-20                      Test::Cmd(3)
Impressum