1Cmd(3) User Contributed Perl Documentation Cmd(3)
2
6 Test::Cmd - Perl module for portable testing of commands and scripts
7
9 use Test::Cmd;
10 $test = Test::Cmd->new(prog => 'program_or_script_to_test',
12 interpreter => 'script_interpreter',
13 string => 'identifier_string',
14 workdir => '',
15 subdir => 'dir',
16 match_sub => $code_ref,
17 verbose => 1);
18 $test->verbose(1);
20 $test->prog('program_or_script_to_test');
22 $test->basename(@suffixlist);
24 $test->interpreter('script_interpreter');
26 $test->string('identifier string');
28 $test->workdir('prefix');
30 $test->workpath('subdir', 'file');
32 $test->subdir('subdir', ...);
34 $test->subdir(['sub', 'dir'], ...);
35 $test->write('file', <<'EOF');
37 contents of file
38 EOF
39 $test->write(['subdir', 'file'], <<'EOF');
40 contents of file
41 EOF
42 $test->read(\$contents, 'file');
44 $test->read(\@lines, 'file');
45 $test->read(\$contents, ['subdir', 'file']);
46 $test->read(\@lines, ['subdir', 'file']);
47 $test->writable('dir');
49 $test->writable('dir', $rwflag);
50 $test->writable('dir', $rwflag, \%errors);
51 $test->preserve(condition, ...);
53 $test->cleanup(condition);
55 $test->run(prog => 'program_or_script_to_test',
57 interpreter => 'script_interpreter',
58 chdir => 'dir', args => 'arguments', stdin => <<'EOF');
59 input to program
60 EOF
61 $test->pass(condition);
63 $test->pass(condition, \&func);
64 $test->fail(condition);
66 $test->fail(condition, \&func);
67 $test->fail(condition, \&func, $caller);
68 $test->no_result(condition);
70 $test->no_result(condition, \&func);
71 $test->no_result(condition, \&func, $caller);
72 $test->stdout;
74 $test->stdout($run_number);
75 $test->stderr;
77 $test->stderr($run_number);
78 $test->match(\@lines, \@matches);
80 $test->match($lines, $matches);
81 $test->match_exact(\@lines, \@matches);
83 $test->match_exact($lines, $matches);
84 $test->match_regex(\@lines, \@regexes);
86 $test->match_regex($lines, $regexes);
87 $test->diff_exact(\@lines, \@matches, \@output);
89 $test->diff_exact($lines, $matches, \@output);
90 $test->diff_regex(\@lines, \@regexes, \@output);
92 $test->diff_regex($lines, $regexes, \@output);
93 sub func {
95 my ($self, $lines, $matches) = @_;
96 # code to match $lines and $matches
97 }
98 $test->match_sub(\&func);
99 $test->match_sub(sub { code to match $_[1] and $_[2] });
100 $test->here;
102
104 The "Test::Cmd" module provides a low-level framework for portable
105 automated testing of executable commands and scripts (in any language,
106 not just Perl), especially commands and scripts that interact with the
107 file system.
108 The "Test::Cmd" module makes no assumptions about what constitutes a
110 successful or failed test. Attempting to read a file that doesn't
111 exist, for example, may or may not be an error, depending on the soft‐
112 ware being tested.
113 Consequently, no "Test::Cmd" methods (including the "new()" method)
115 exit, die or throw any other sorts of exceptions (but they all do
116 return useful error indications). Exceptions or other error status
117 should be handled by a higher layer: a subclass of "Test::Cmd", or
118 another testing framework such as the "Test" or "Test::Simple" Perl
119 modules, or by the test itself.
120 (That said, see the "Test::Cmd::Common" module if you want a similar
122 module that provides exception handling, either to use directly in your
123 own tests, or as an example of how to use "Test::Cmd".)
124 In addition to running tests and evaluating conditions, the "Test::Cmd"
126 module manages and cleans up one or more temporary workspace directo‐
127 ries, and provides methods for creating files and directories in those
128 workspace directories from in-line data (that is, here-documents),
129 allowing tests to be completely self-contained. When used in conjunc‐
130 tion with another testing framework, the "Test::Cmd" module can func‐
131 tion as a fixture (common startup code for multiple tests) for simple
132 management of command execution and temporary workspaces.
133 The "Test::Cmd" module inherits "File::Spec" methods
135 ("file_name_is_absolute()", "catfile()", etc.) to support writing tests
136 portably across a variety of operating and file systems.
137 A "Test::Cmd" environment object is created via the usual invocation:
139 $test = Test::Cmd->new();
141 Arguments to the "Test::Cmd::new" method are keyword-value pairs that
143 may be used to initialize the object, typically by invoking the same-
144 named method as the keyword.
145
147 As mentioned, because the "Test::Cmd" module makes no assumptions about
148 what constitutes success or failure of a test, it can be used to pro‐
149 vide temporary workspaces, other file system interaction, or command
150 execution for a variety of testing frameworks. This section describes
151 how to use the "Test::Cmd" with several different higher-layer testing
152 frameworks.
153 Note that you should not intermix multiple testing frameworks in a sin‐
155 gle testing script.
156 "Test::Harness"
158 The "Test::Cmd" module may be used in tests that print results in a
160 format suitable for the standard Perl "Test::Harness" module:
161 use Test::Cmd;
163 print "1..5\n";
165 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
167 if ($test) { print "ok 1\n"; } else { print "not ok 1\n"; }
168 $input = <<_EOF;
170 test_program should process this input
171 and exit successfully (status 0).
172 _EOF_
173 $wrote_file = $test->write('input_file', $input);
175 if ($wrote_file) { print "ok 2\n"; } else { print "not ok 2\n"; }
176 $test->run(args => '-x input_file');
178 if ($? == 0) { print "ok 3\n"; } else { print "not ok 3\n"; }
179 $wrote_file = $test->write('input_file', $input);
181 if ($wrote_file) { print "ok 4\n"; } else { print "not ok 4\n"; }
182 $test->run(args => '-y input_file');
184 if ($? == 0) { print "ok 5\n"; } else { print "not ok 5\n"; }
185 Several other Perl modules simplify the use of "Test::Harness" by elim‐
187 inating the need to hand-code the "print" statements and test numbers.
188 The "Test" module, the "Test::Simple" module, and the "Test::More" mod‐
189 ule all export an "ok()" subroutine to test conditions. Here is how
190 the above example would look rewritten to use "Test::Simple":
191 use Test::Simple tests => 5;
193 use Test::Cmd;
194 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
196 ok($test, "creating Test::Cmd object");
197 $input = <<_EOF;
199 test_program should process this input
200 and exit successfully (status 0).
201 _EOF_
202 $wrote_file = $test->write('input_file', $input);
204 ok($wrote_file, "writing input_file");
205 $test->run(args => '-x input_file');
207 ok($? == 0, "executing test_program -x input_file");
208 $wrote_file = $test->write('input_file', $input);
210 ok($wrote_file, "writing input_file");
211 $test->run(args => '-y input_file');
213 ok($? == 0, "executing test_program -y input_file");
214 "Test::Unit"
216 The Perl "Test::Unit" package provides a procedural testing interface
218 modeled after a testing framework widely used in the eXtreme Program‐
219 ming development methodology. The "Test::Cmd" module can function as
220 part of a "Test::Unit" fixture that can set up workspaces as needed for
221 a set of tests. This avoids having to repeat code to re-initialize an
222 input file multiple times:
223 use Test::Unit;
225 use Test::Cmd;
226 my $test;
228 $input = <<'EOF';
230 test_program should process this input
231 and exit successfully (status 0).
232 EOF
233 sub set_up {
235 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
236 $test->write('input_file', $input);
237 }
238 sub test_x {
240 my $result = $test->run(args => '-x input_file');
241 assert($result == 0, "failed test_x\n");
242 }
243 sub test_y {
245 my $result = $test->run(args => '-y input_file');
246 assert($result == 0, "failed test_y\n");
247 }
248 create_suite();
250 run_suite;
251 Note that, because the "Test::Cmd" module takes care of cleaning up
253 temporary workspaces on exit, there is no need to remove explicitly the
254 workspace in a "tear_down" subroutine. (There may, of course, be other
255 things in the test that need a "tear_down" subroutine.)
256 Aegis
258 Alternatively, the "Test::Cmd" module provides "pass()", "fail()", and
260 "no_result()" methods that can be used to provide an appropriate exit
261 status and simple printed indication for a test. These methods termi‐
262 nate the test immediately, reporting "PASSED", "FAILED", or "NO RESULT"
263 respectively, and exiting with status 0 (success), 1 or 2 respectively.
264 The separate "fail()" and "no_result()" methods allow for a distinction
266 between an actual failed test and a test that could not be properly
267 evaluated because of an external condition (such as a full file system
268 or incorrect permissions).
269 The exit status values happen to match the requirements of the Aegis
271 change management system, and the printed strings are based on existing
272 Aegis conventions. They are not really Aegis-specific, however, and
273 provide a simple, useful starting point if you don't already have
274 another testing framework:
275 use Test::Cmd;
277 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
279 Test::Cmd->no_result(! $test);
280 $input = <<EOF;
282 test_program should process this input
283 and exit successfully (status 0).
284 EOF
285 $wrote_file = $test->write('input_file', $input);
287 $test->no_result(! $wrote_file);
288 $test->run(args => '-x input_file');
290 $test->fail($? != 0);
291 $wrote_file = $test->write('input_file', $input);
293 $test->no_result(! $wrote_file);
294 $test->run(args => '-y input_file');
296 $test->fail($? != 0);
297 $test->pass;
299 Note that the separate "Test::Cmd::Common" wrapper module can simplify
301 the above example even further by taking care of common exception han‐
302 dling cases within the testing object itself.
303 use Test::Cmd::Common;
305 $test = Test::Cmd::Common->new(prog => 'test_program', workdir => '');
307 $input = <<EOF;
309 test_program should process this input
310 and exit successfully (status 0).
311 EOF
312 $wrote_file = $test->write('input_file', $input);
314 $test->run(args => '-x input_file');
316 $wrote_file = $test->write('input_file', $input);
318 $test->run(args => '-y input_file');
320 $test->pass;
322 See the "Test::Cmd::Common" module for details.
324
326 Methods supported by the "Test::Cmd" module include:
327 "new"
329 Create a new "Test::Cmd" environment. Arguments with which to ini‐
330 tialize the environment are passed in as keyword-value pairs.
331 Fails if a specified temporary working directory or subdirectory
332 cannot be created. Does NOT die or exit on failure, but returns
333 FALSE if the test environment object cannot be created.
334 "verbose"
336 Sets the verbose level for the environment object to the specified
337 value.
338 "prog"
340 Specifies the executable program or script to be tested. Returns
341 the absolute path name of the current program or script.
342 "basename"
344 Returns the basename of the current program or script. Any speci‐
345 fied arguments are a list of file suffixes that may be stripped
346 from the basename.
347 "interpreter"
349 Specifies the program to be used to interpret "prog" as a script.
350 Returns the current value of "interpreter".
351 "string"
353 Specifies an identifier string for the functionality being tested
354 to be printed on failure or no result.
355 "workdir"
357 When an argument is specified, creates a temporary working direc‐
358 tory with the specified name. If the argument is a NULL string
359 (''), the directory is named "testcmd" by default, followed by the
360 unique ID of the executing process.
361 Returns the absolute pathname to the temporary working directory,
363 or FALSE if the directory could not be created.
364 "workpath"
366 Returns the absolute path name to a subdirectory or file under the
367 current temporary working directory by concatenating the temporary
368 working directory name with the specified arguments.
369 "subdir"
371 Creates new subdirectories under the temporary working dir, one for
372 each argument. An argument may be an array reference, in which
373 case the array elements are concatenated together using the
374 "File::Spec-&"catfile> method. Subdirectories multiple levels deep
375 must be created via a separate argument for each level:
376 $test->subdir('sub', ['sub', 'dir'], [qw(sub dir ectory)]);
378 Returns the number of subdirectories actually created.
380 "write"
382 Writes the specified text (second argument) to the specified file
383 name (first argument). The file name may be an array reference, in
384 which case all the array elements except the last are subdirectory
385 names to be concatenated together. The file is created under the
386 temporary working directory. Any subdirectories in the path must
387 already exist.
388 "read"
390 Reads the contents of the specified file name (second argument)
391 into the scalar or array referred to by the first argument. The
392 file name may be an array reference, in which case all the array
393 elements except the last are subdirectory names to be concatenated
394 together. The file is assumed to be under the temporary working
395 directory unless it is an absolute path name.
396 Returns TRUE on successfully opening and reading the file, FALSE
398 otherwise.
399 "writable"
401 Makes every file and directory within the specified directory tree
402 writable ("rwflag" == TRUE) or not writable ("rwflag" == FALSE).
403 The default is to make the directory tree writable. Optionally
404 fills in the supplied hash reference with a hash of path names that
405 could not have their permissions set appropriately, with the reason
406 why each could not be set.
407 "preserve"
409 Arranges for the temporary working directories for the specified
410 "Test::Cmd" environment to be preserved for one or more conditions.
411 If no conditions are specified, arranges for the temporary working
412 directories to be preserved for all conditions.
413 "cleanup"
415 Removes any temporary working directories for the specified
416 "Test::Cmd" environment. If the environment variable "PRESERVE"
417 was set when the "Test::Cmd" module was loaded, temporary working
418 directories are not removed. If any of the environment variables
419 "PRESERVE_PASS", "PRESERVE_FAIL", or "PRESERVE_NO_RESULT" were set
420 when the "Test::Cmd" module was loaded, then temporary working
421 directories are not removed if the test passed, failed, or had no
422 result, respectively. Temporary working directories are also pre‐
423 served for conditions specified via the "preserve" method.
424 Typically, this method is not called directly, but is used when the
426 script exits to clean up temporary working directories as appropri‐
427 ate for the exit status.
428 "run"
430 Runs a test of the program or script for the test environment.
431 Standard output and error output are saved for future retrieval via
432 the "stdout" and "stderr" methods.
433 Arguments are supplied as keyword-value pairs:
435 "args"
437 Specifies the command-line arguments to be supplied to the pro‐
438 gram or script under test for this run:
439 $test->run(args => 'arg1 arg2');
441 "chdir"
443 Changes directory to the path specified as the value argument:
444 $test->run(chdir => 'xyzzy');
446 If the specified path is not an absolute path name (begins with
448 '/' on Unix systems), then the subdirectory is relative to the
449 temporary working directory for the environment
450 ("$test-&"workdir>). Note that, by default, the "Test::Cmd"
451 module does NOT chdir to the temporary working directory, so to
452 execute the test under the temporary working directory, you
453 must specify an explicit "chdir" to the current directory:
454 $test->run(chdir => '.'); # Unix-specific
456 $test->run(chdir => $test->curdir); # portable
458 "interpreter"
460 Specifies the program to be used to interpret "prog" as a
461 script, for this run only. This does not change the
462 "$test-&"interpreter> value of the test environment.
463 "prog"
465 Specifies the executable program or script to be run, for this
466 run only. This does not change the "$test-&"prog> value of the
467 test environment.
468 "stdin"
470 Pipes the specified value (string or array ref) to the program
471 or script under test for this run:
472 $test->run(stdin => <<_EOF_);
474 input to the program under test
475 _EOF_
476 Returns the exit status of the program or script.
478 "pass"
480 Exits the test successfully. Reports "PASSED" on the error output
481 and exits with a status of 0. If a condition is supplied, only
482 exits the test if the condition evaluates TRUE. If a function ref‐
483 erence is supplied, executes the function before reporting and
484 exiting.
485 "fail"
487 Exits the test unsuccessfully. Reports "FAILED test of {string} at
488 line {line} of {file}." on the error output and exits with a status
489 of 1. If a condition is supplied, only exits the test if the con‐
490 dition evaluates TRUE. If a function reference is supplied, exe‐
491 cutes the function before reporting and exiting. If a caller level
492 is supplied, prints a simple calling trace N levels deep as part of
493 reporting the failure.
494 "no_result"
496 Exits the test with an indeterminate result (the test could not be
497 performed due to external conditions such as, for example, a full
498 file system). Reports "NO RESULT for test of {string} at line
499 {line} of {file}." on the error output and exits with a status of
500 2. If a condition is supplied, only exits the test if the condi‐
501 tion evaluates TRUE. If a function reference is supplied, executes
502 the function before reporting and exiting. If a caller level is
503 supplied, prints a simple calling trace N levels deep as part of
504 reporting the failure.
505 "stdout"
507 Returns the standard output from the specified run number. If
508 there is no specified run number, then returns the standard output
509 of the last run. Returns the standard output as either a scalar or
510 an array of output lines, as appropriate for the calling context.
511 Returns "undef" if there has been no test run.
512 "stderr"
514 Returns the error output from the specified run number. If there
515 is no specified run number, then returns the error output of the
516 last run. Returns the error output as either a scalar or an array
517 of output lines, as apporpriate for the calling context. Returns
518 "undef" if there has been no test run.
519 "match"
521 Matches one or more input lines against an equal number of expected
522 lines using the currently-registered line-matching function. The
523 default line-matching function is the "match_regex" method, which
524 means that the default is to match lines against regular expres‐
525 sions.
526 "match_exact"
528 Compares two arrays of lines for exact matches. The arguments are
529 passed in as either scalars, in which case each is split on newline
530 boundaries, or as array references. An unequal number of lines in
531 the two arrays fails immediately and returns FALSE before any com‐
532 parisons are performed.
533 Returns TRUE if each line matched its corresponding line in the
535 other array, FALSE otherwise.
536 "match_regex"
538 Matches one or more input lines against an equal number of regular
539 expressions. The arguments are passed in as either scalars, in
540 which case each is split on newline boundaries, or as array refer‐
541 ences. Trailing newlines are stripped from each line and regular
542 expression. An unequal number of lines and regular expressions
543 fails immediately and returns FALSE before any comparisons are per‐
544 formed. Comparison is performed for each entire line, that is,
545 with each regular expression anchored at both the start of line (^)
546 and end of line ($).
547 Returns TRUE if each line matched each regular expression, FALSE
549 otherwise.
550 "diff_exact"
552 Diffs two arrays of lines in a manner similar to the UNIX diff(1)
553 utility.
554 If the "Algorithm::DiffOld" package is installed on the local sys‐
556 tem, output describing the differences between the input lines and
557 the matching lines, in diff(1) format, is saved to the $output
558 array reference. In the diff output, the expected output lines are
559 considered the "old" (left-hand) file, and the actual output is
560 considered the "new" (right-hand) file.
561 If the "Algorithm::DiffOld" package is not installed on the local
563 system, the Expected and Actual contents are saved as-is to the
564 $output array reference.
565 The "lines" and "matches" arguments are passed in as either
567 scalars, in which case each is split on newline boundaries, or as
568 array references. Trailing newlines are stripped from each line
569 and regular expression.
570 Returns TRUE if each line matched its corresponding line in the
572 expected matches, FALSE otherwise, in order to conform to the con‐
573 ventions of the "match" method.
574 Typical invocation:
576 if (! $test->diff_exact($test->stdout,
578 \@expected_lines,
579 \@diff)) {
580 print @diff;
581 }
582 "diff_regex"
584 Diffs one or more input lines against one or more regular expres‐
585 sions in a manner similar to the UNIX diff(1) utility.
586 If the "Algorithm::DiffOld" package is installed on the local sys‐
588 tem, output describing the differences between the input lines and
589 the matching lines, in diff(1) format, is saved to the $output
590 array reference. In the diff output, the expected output lines are
591 considered the "old" (left-hand) file, and the actual output is
592 considered the "new" (right-hand) file.
593 If the "Algorithm::DiffOld" package is not installed on the local
595 system, the Expected and Actual contents are saved as-is to the
596 $output array reference.
597 The "lines" and "regexes" arguments are passed in as either
599 scalars, in which case each is split on newline boundaries, or as
600 array references. Trailing newlines are stripped from each line
601 and regular expression. Comparison is performed for each entire
602 line, that is, with each regular expression anchored at both the
603 start of line (^) and end of line ($).
604 Returns TRUE if each line matched each regular expression, FALSE
606 otherwise, in order to conform to the conventions of the "match"
607 method.
608 Typical invocation:
610 if (! $test->diff_regex($test->stdout,
612 \@expected_lines,
613 \@diff)) {
614 print @diff;
615 }
616 "match_sub"
618 Registers the specified code reference as the line-matching func‐
619 tion to be called by the "match" method. This can be a user-sup‐
620 plied subroutine, or the "match_exact", "match_regex",
621 "diff_exact", or "diff_regex" methods supplied by the "Test::Cmd"
622 module:
623 $test->match_sub(\&Test::Cmd::match_exact);
625 $test->match_sub(\&Test::Cmd::match_regex);
627 $test->match_sub(\&Test::Cmd::diff_exact);
629 $test->match_sub(\&Test::Cmd::diff_regex);
631 The "match_exact", "match_regex", "diff_exact" and "diff_regex"
633 subroutine names are exportable from the "Test::Cmd" module, and
634 may be specified at object initialization:
635 use Test::Cmd qw(match_exact match_regex diff_exact diff_regex);
637 $test_exact = Test::Cmd->new(match_sub => \&match_exact);
638 $test_regex = Test::Cmd->new(match_sub => \&match_regex);
639 $test_exact = Test::Cmd->new(match_sub => \&diff_exact);
640 $test_regex = Test::Cmd->new(match_sub => \&diff_regex);
641 "here"
643 Returns the absolute path name of the current working directory.
644 (This is essentially the same as the "Cwd::cwd" method, except that
645 the "Test::Cmd::here" method preserves the directory separators
646 exactly as returned by the underlying operating-system-dependent
647 method. The "Cwd::cwd" method canonicalizes all directory separa‐
648 tors to '/', which makes for consistent path name representations
649 within Perl, but may mess up another program or script to which you
650 try to pass the path name.)
651
653 Several environment variables affect the default values in a newly cre‐
654 ated "Test::Cmd" environment object. These environment variables must
655 be set when the module is loaded, not when the object is created.
656 "PRESERVE"
658 If set to a true value, all temporary working directories will be
659 preserved on exit, regardless of success or failure of the test.
660 The full path names of all temporary working directories will be
661 reported on error output.
662 "PRESERVE_FAIL"
664 If set to a true value, all temporary working directories will be
665 preserved on exit from a failed test. The full path names of all
666 temporary working directories will be reported on error output.
667 "PRESERVE_NO_RESULT"
669 If set to a true value, all temporary working directories will be
670 preserved on exit from a test for which there is no result. The
671 full path names of all temporary working directories will be
672 reported on error output.
673 "PRESERVE_PASS"
675 If set to a true value, all temporary working directories will be
676 preserved on exit from a successful test. The full path names of
677 all temporary working directories will be reported on error output.
678 "VERBOSE"
680 When set to a true value, enables verbose reporting of various
681 internal things (path names, exact command line being executed,
682 etc.).
683
685 Although the "Test::Cmd" module is intended to make it easier to write
686 portable tests for portable utilities that interact with file systems,
687 it is still very easy to write non-portable tests if you're not care‐
688 ful.
689 The best and most comprehensive set of portability guidelines is the
691 standard "Writing portable Perl" document at:
692 http://www.perl.com/pub/doc/manual/html/pod/perlport.html
694 To reiterate one important point from the "WpP" document: Not all Perl
696 programs have to be portable. If the program or script you're testing
697 is UNIX-specific, you can (and should) use the "Test::Cmd" module to
698 write UNIX-specific tests.
699 That having been said, here are some hints that may help keep your
701 tests portable, if that's a requirement.
702 Use the "Test::Cmd-&"here> method for current directory path.
704 The normal Perl way to fetch the current working directory is to
705 use the "Cwd::cwd" method. Unfortunately, the "Cwd::cwd" method
706 canonicalizes the path name it returns, changing the native direc‐
707 tory separators into the forward slashes favored by Perl and UNIX.
708 For most Perl scripts, this makes a great deal of sense and keeps
709 code uncluttered.
710 Passing in a file name that has had its directory separators
712 altered, however, may confuse the command or script under test, or
713 make it difficult to compare output from the command or script with
714 an expected result. The "Test::Cmd::here" method returns the abso‐
715 lute path name of the current working directory, like "Cwd::cwd",
716 but does not manipulate the returned path in any way.
717 Use "File::Spec" methods for manipulating path names.
719 The "File::Spec" module provides a system-independent interface for
720 manipulating path names. Because the "Test::Cmd" class is a sub-
721 class of the "File::Spec" class, you can use these methods directly
722 as follows:
723 if (! Test::Cmd->file_name_is_absolute($prog)) {
725 my $prog = Test::Cmd->catfile(Test::Cmd->here, $prog);
726 }
727 For details about the available methods and their use, see the doc‐
729 umentation for the "File::Spec" module and its sub-modules, espe‐
730 cially the "File::Spec::Unix" modules.
731 Use "Config" for file-name suffixes, where possible.
733 The standard "Config" module provides values that reflect the file-
734 name suffixes on the system for which the Perl executable was
735 built. This provides convenient portability for situations where a
736 file name may have different extensions on different systems:
737 $foo_exe = "foo$Config{_exe}";
739 ok(-f $foo_exe);
740 (Unfortunately, there is no existing $Config value that specifies
742 the suffix for a directly-executable Perl script.)
743 Avoid generating executable programs or scripts.
745 How to make a file or script executable varies widely from system
746 to system, some systems using file name extensions to indicate exe‐
747 cutability, others using a file permission bit. The differences
748 are complicated to accomodate in a portable test script. The easi‐
749 est way to deal with this complexity is to avoid it if you can.
750 If your test somehow requires executing a script that you generate
752 from the test itself, the best way is to generate the script in
753 Perl and then explicitly feed it to the Perl executable on the
754 local system. To be maximally portable, use the $^X variable
755 instead of hard-coding "perl" into the string you execute:
756 $line = "This is output from the generated perl script.";
758 $test->write('script', <<EOF);
759 print STDOUT "$line\\n";
760 EOF
761 $output = `$^X script`;
762 ok($output eq "$line\n");
763 This completely avoids having to make the "script" file itself exe‐
765 cutable. (Since you're writing your test in Perl, it's safe to
766 assume that Perl itself is executable.)
767 If you must generate a directly-executable script, then use the
769 $Config{'startperl'} variable at the start of the script to gener‐
770 ate the appropriate magic that will execute it as a Perl script:
771 use Config;
773 $line = "This is output from the generated perl script.";
774 $test->write('script', <<EOF);
775 $Config{'startperl'};
776 print STDOUT "$line\\n";
777 EOF
778 chdir($test->workdir);
779 chmod(0755, 'script'); # POSIX-SPECIFIC
780 $output = `script`;
781 ok($output eq "$line\n");
782 Addtional hints on writing portable tests are welcome.
784
786 perl(1), Algorithm::DiffOld(3), File::Find(3), File::Spec(3), Test(3),
787 Test::Cmd::Common(3), Test::Harness(3), Test::More(3), Test::Simple(3),
788 Test::Unit(3).
789 A rudimentary page for the "Test::Cmd" module is available at:
791 http://www.baldmt.com/Test-Cmd/
793 The most involved example of using the "Test::Cmd" package to test a
795 real-world application is the "cons-test" testing suite for the Cons
796 software construction utility. The suite uses a sub-class of
797 "Test::Cmd::Common" (which in turn is a sub-class of "Test::Cmd") to
798 provide common, application-specific infrastructure across a large num‐
799 ber of end-to-end application tests. The suite, and other information
800 about Cons, is available at:
801 http://www.dsmit.com/cons
803
805 Steven Knight, knight@baldmt.com
806
808 Copyright 1999-2001 Steven Knight. All rights reserved. This program
809 is free software; you can redistribute it and/or modify it under the
810 same terms as Perl itself.
811
813 Thanks to Greg Spencer for the inspiration to create this package and
814 the initial draft of its implementation as a specific testing package
815 for the Cons software construction utility. Information about Cons is
816 available at:
817 http://www.dsmit.com/cons/
819 The general idea of managing temporary working directories in this way,
821 as well as the test reporting of the "pass", "fail" and "no_result"
822 methods, come from the testing framework invented by Peter Miller for
823 his Aegis project change supervisor. Aegis is an excellent bit of work
824 which integrates creation and execution of regression tests into the
825 software development process. Information about Aegis is available at:
826 http://www.tip.net.au/~millerp/aegis.html
828 Thanks to Michael Schwern for all of the thoughtful work he's put into
830 Perl's standard testing methodology, including the "Test::Simple" and
831 "Test::More" modules, and enhancement and maintenance of the "Test" and
832 "Test::Harness" modules. Thanks also to Christian Lemburg for the
833 impressively complete "Test::Unit" framework of modules. Ideas from
834 both have helped keep "Test::Cmd" flexible enough to be useful in mul‐
835 tiple testing frameworks.
836perl v5.8.8 2001-09-05 Cmd(3)