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
112 software 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
127 directories, and provides methods for creating files and directories in
128 those workspace directories from in-line data (that is, here-
129 documents), allowing tests to be completely self-contained. When used
130 in conjunction with another testing framework, the "Test::Cmd" module
131 can function as a fixture (common startup code for multiple tests) for
132 simple 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
149 provide 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
155 single testing script.
156 "Test::Harness"
158 The "Test::Cmd" module may be used in tests that print results in a
159 format suitable for the standard Perl "Test::Harness" module:
160 use Test::Cmd;
162 print "1..5\n";
164 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
166 if ($test) { print "ok 1\n"; } else { print "not ok 1\n"; }
167 $input = <<_EOF;
169 test_program should process this input
170 and exit successfully (status 0).
171 _EOF_
172 $wrote_file = $test->write('input_file', $input);
174 if ($wrote_file) { print "ok 2\n"; } else { print "not ok 2\n"; }
175 $test->run(args => '-x input_file');
177 if ($? == 0) { print "ok 3\n"; } else { print "not ok 3\n"; }
178 $wrote_file = $test->write('input_file', $input);
180 if ($wrote_file) { print "ok 4\n"; } else { print "not ok 4\n"; }
181 $test->run(args => '-y input_file');
183 if ($? == 0) { print "ok 5\n"; } else { print "not ok 5\n"; }
184 Several other Perl modules simplify the use of "Test::Harness" by
186 eliminating the need to hand-code the "print" statements and test
187 numbers. The "Test" module, the "Test::Simple" module, and the
188 "Test::More" module all export an "ok()" subroutine to test conditions.
189 Here is how the above example would look rewritten to use
190 "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
217 modeled after a testing framework widely used in the eXtreme
218 Programming development methodology. The "Test::Cmd" module can
219 function as part of a "Test::Unit" fixture that can set up workspaces
220 as needed for a set of tests. This avoids having to repeat code to re-
221 initialize an input file multiple times:
222 use Test::Unit;
224 use Test::Cmd;
225 my $test;
227 $input = <<'EOF';
229 test_program should process this input
230 and exit successfully (status 0).
231 EOF
232 sub set_up {
234 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
235 $test->write('input_file', $input);
236 }
237 sub test_x {
239 my $result = $test->run(args => '-x input_file');
240 assert($result == 0, "failed test_x\n");
241 }
242 sub test_y {
244 my $result = $test->run(args => '-y input_file');
245 assert($result == 0, "failed test_y\n");
246 }
247 create_suite();
249 run_suite;
250 Note that, because the "Test::Cmd" module takes care of cleaning up
252 temporary workspaces on exit, there is no need to remove explicitly the
253 workspace in a "tear_down" subroutine. (There may, of course, be other
254 things in the test that need a "tear_down" subroutine.)
255 Aegis
257 Alternatively, the "Test::Cmd" module provides "pass()", "fail()", and
258 "no_result()" methods that can be used to provide an appropriate exit
259 status and simple printed indication for a test. These methods
260 terminate the test immediately, reporting "PASSED", "FAILED", or "NO
261 RESULT" respectively, and exiting with status 0 (success), 1 or 2
262 respectively.
263 The separate "fail()" and "no_result()" methods allow for a distinction
265 between an actual failed test and a test that could not be properly
266 evaluated because of an external condition (such as a full file system
267 or incorrect permissions).
268 The exit status values happen to match the requirements of the Aegis
270 change management system, and the printed strings are based on existing
271 Aegis conventions. They are not really Aegis-specific, however, and
272 provide a simple, useful starting point if you don't already have
273 another testing framework:
274 use Test::Cmd;
276 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
278 Test::Cmd->no_result(! $test);
279 $input = <<EOF;
281 test_program should process this input
282 and exit successfully (status 0).
283 EOF
284 $wrote_file = $test->write('input_file', $input);
286 $test->no_result(! $wrote_file);
287 $test->run(args => '-x input_file');
289 $test->fail($? != 0);
290 $wrote_file = $test->write('input_file', $input);
292 $test->no_result(! $wrote_file);
293 $test->run(args => '-y input_file');
295 $test->fail($? != 0);
296 $test->pass;
298 Note that the separate "Test::Cmd::Common" wrapper module can simplify
300 the above example even further by taking care of common exception
301 handling cases within the testing object itself.
302 use Test::Cmd::Common;
304 $test = Test::Cmd::Common->new(prog => 'test_program', workdir => '');
306 $input = <<EOF;
308 test_program should process this input
309 and exit successfully (status 0).
310 EOF
311 $wrote_file = $test->write('input_file', $input);
313 $test->run(args => '-x input_file');
315 $wrote_file = $test->write('input_file', $input);
317 $test->run(args => '-y input_file');
319 $test->pass;
321 See the "Test::Cmd::Common" module for details.
323
325 Methods supported by the "Test::Cmd" module include:
326 "new"
328 Create a new "Test::Cmd" environment. Arguments with which to
329 initialize the environment are passed in as keyword-value pairs.
330 Fails if a specified temporary working directory or subdirectory
331 cannot be created. Does NOT die or exit on failure, but returns
332 FALSE if the test environment object cannot be created.
333 "verbose"
335 Sets the verbose level for the environment object to the specified
336 value.
337 "prog"
339 Specifies the executable program or script to be tested. Returns
340 the absolute path name of the current program or script.
341 "basename"
343 Returns the basename of the current program or script. Any
344 specified arguments are a list of file suffixes that may be
345 stripped from the basename.
346 "interpreter"
348 Specifies the program to be used to interpret "prog" as a script.
349 Returns the current value of "interpreter".
350 "string"
352 Specifies an identifier string for the functionality being tested
353 to be printed on failure or no result.
354 "workdir"
356 When an argument is specified, creates a temporary working
357 directory with the specified name. If the argument is a NULL
358 string (''), the directory is named "testcmd" by default, followed
359 by the unique ID of the executing process.
360 Returns the absolute pathname to the temporary working directory,
362 or FALSE if the directory could not be created.
363 "workpath"
365 Returns the absolute path name to a subdirectory or file under the
366 current temporary working directory by concatenating the temporary
367 working directory name with the specified arguments.
368 "subdir"
370 Creates new subdirectories under the temporary working dir, one for
371 each argument. An argument may be an array reference, in which
372 case the array elements are concatenated together using the
373 "File::Spec-&"catfile> method. Subdirectories multiple levels deep
374 must be created via a separate argument for each level:
375 $test->subdir('sub', ['sub', 'dir'], [qw(sub dir ectory)]);
377 Returns the number of subdirectories actually created.
379 "write"
381 Writes the specified text (second argument) to the specified file
382 name (first argument). The file name may be an array reference, in
383 which case all the array elements except the last are subdirectory
384 names to be concatenated together. The file is created under the
385 temporary working directory. Any subdirectories in the path must
386 already exist.
387 "read"
389 Reads the contents of the specified file name (second argument)
390 into the scalar or array referred to by the first argument. The
391 file name may be an array reference, in which case all the array
392 elements except the last are subdirectory names to be concatenated
393 together. The file is assumed to be under the temporary working
394 directory unless it is an absolute path name.
395 Returns TRUE on successfully opening and reading the file, FALSE
397 otherwise.
398 "writable"
400 Makes every file and directory within the specified directory tree
401 writable ("rwflag" == TRUE) or not writable ("rwflag" == FALSE).
402 The default is to make the directory tree writable. Optionally
403 fills in the supplied hash reference with a hash of path names that
404 could not have their permissions set appropriately, with the reason
405 why each could not be set.
406 "preserve"
408 Arranges for the temporary working directories for the specified
409 "Test::Cmd" environment to be preserved for one or more conditions.
410 If no conditions are specified, arranges for the temporary working
411 directories to be preserved for all conditions.
412 "cleanup"
414 Removes any temporary working directories for the specified
415 "Test::Cmd" environment. If the environment variable "PRESERVE"
416 was set when the "Test::Cmd" module was loaded, temporary working
417 directories are not removed. If any of the environment variables
418 "PRESERVE_PASS", "PRESERVE_FAIL", or "PRESERVE_NO_RESULT" were set
419 when the "Test::Cmd" module was loaded, then temporary working
420 directories are not removed if the test passed, failed, or had no
421 result, respectively. Temporary working directories are also
422 preserved for conditions specified via the "preserve" method.
423 Typically, this method is not called directly, but is used when the
425 script exits to clean up temporary working directories as
426 appropriate for the exit status.
427 "run"
429 Runs a test of the program or script for the test environment.
430 Standard output and error output are saved for future retrieval via
431 the "stdout" and "stderr" methods.
432 Arguments are supplied as keyword-value pairs:
434 "args"
436 Specifies the command-line arguments to be supplied to the
437 program or script under test for this run:
438 $test->run(args => 'arg1 arg2');
440 "chdir"
442 Changes directory to the path specified as the value argument:
443 $test->run(chdir => 'xyzzy');
445 If the specified path is not an absolute path name (begins with
447 '/' on Unix systems), then the subdirectory is relative to the
448 temporary working directory for the environment
449 ("$test-&"workdir>). Note that, by default, the "Test::Cmd"
450 module does NOT chdir to the temporary working directory, so to
451 execute the test under the temporary working directory, you
452 must specify an explicit "chdir" to the current directory:
453 $test->run(chdir => '.'); # Unix-specific
455 $test->run(chdir => $test->curdir); # portable
457 "interpreter"
459 Specifies the program to be used to interpret "prog" as a
460 script, for this run only. This does not change the
461 "$test-&"interpreter> value of the test environment.
462 "prog"
464 Specifies the executable program or script to be run, for this
465 run only. This does not change the "$test-&"prog> value of the
466 test environment.
467 "stdin"
469 Pipes the specified value (string or array ref) to the program
470 or script under test for this run:
471 $test->run(stdin => <<_EOF_);
473 input to the program under test
474 _EOF_
475 Returns the exit status of the program or script.
477 "pass"
479 Exits the test successfully. Reports "PASSED" on the error output
480 and exits with a status of 0. If a condition is supplied, only
481 exits the test if the condition evaluates TRUE. If a function
482 reference is supplied, executes the function before reporting and
483 exiting.
484 "fail"
486 Exits the test unsuccessfully. Reports "FAILED test of {string} at
487 line {line} of {file}." on the error output and exits with a status
488 of 1. If a condition is supplied, only exits the test if the
489 condition evaluates TRUE. If a function reference is supplied,
490 executes the function before reporting and exiting. If a caller
491 level is supplied, prints a simple calling trace N levels deep as
492 part of reporting the failure.
493 "no_result"
495 Exits the test with an indeterminate result (the test could not be
496 performed due to external conditions such as, for example, a full
497 file system). Reports "NO RESULT for test of {string} at line
498 {line} of {file}." on the error output and exits with a status of
499 2. If a condition is supplied, only exits the test if the
500 condition evaluates TRUE. If a function reference is supplied,
501 executes the function before reporting and exiting. If a caller
502 level is supplied, prints a simple calling trace N levels deep as
503 part of reporting the failure.
504 "stdout"
506 Returns the standard output from the specified run number. If
507 there is no specified run number, then returns the standard output
508 of the last run. Returns the standard output as either a scalar or
509 an array of output lines, as appropriate for the calling context.
510 Returns "undef" if there has been no test run.
511 "stderr"
513 Returns the error output from the specified run number. If there
514 is no specified run number, then returns the error output of the
515 last run. Returns the error output as either a scalar or an array
516 of output lines, as apporpriate for the calling context. Returns
517 "undef" if there has been no test run.
518 "match"
520 Matches one or more input lines against an equal number of expected
521 lines using the currently-registered line-matching function. The
522 default line-matching function is the "match_regex" method, which
523 means that the default is to match lines against regular
524 expressions.
525 "match_exact"
527 Compares two arrays of lines for exact matches. The arguments are
528 passed in as either scalars, in which case each is split on newline
529 boundaries, or as array references. An unequal number of lines in
530 the two arrays fails immediately and returns FALSE before any
531 comparisons are performed.
532 Returns TRUE if each line matched its corresponding line in the
534 other array, FALSE otherwise.
535 "match_regex"
537 Matches one or more input lines against an equal number of regular
538 expressions. The arguments are passed in as either scalars, in
539 which case each is split on newline boundaries, or as array
540 references. Trailing newlines are stripped from each line and
541 regular expression. An unequal number of lines and regular
542 expressions fails immediately and returns FALSE before any
543 comparisons are performed. Comparison is performed for each entire
544 line, that is, with each regular expression anchored at both the
545 start of line (^) and end of line ($).
546 Returns TRUE if each line matched each regular expression, FALSE
548 otherwise.
549 "diff_exact"
551 Diffs two arrays of lines in a manner similar to the UNIX diff(1)
552 utility.
553 If the "Algorithm::DiffOld" package is installed on the local
555 system, output describing the differences between the input lines
556 and the matching lines, in diff(1) format, is saved to the $output
557 array reference. In the diff output, the expected output lines are
558 considered the "old" (left-hand) file, and the actual output is
559 considered the "new" (right-hand) file.
560 If the "Algorithm::DiffOld" package is not installed on the local
562 system, the Expected and Actual contents are saved as-is to the
563 $output array reference.
564 The "lines" and "matches" arguments are passed in as either
566 scalars, in which case each is split on newline boundaries, or as
567 array references. Trailing newlines are stripped from each line
568 and regular expression.
569 Returns TRUE if each line matched its corresponding line in the
571 expected matches, FALSE otherwise, in order to conform to the
572 conventions of the "match" method.
573 Typical invocation:
575 if (! $test->diff_exact($test->stdout,
577 \@expected_lines,
578 \@diff)) {
579 print @diff;
580 }
581 "diff_regex"
583 Diffs one or more input lines against one or more regular
584 expressions in a manner similar to the UNIX diff(1) utility.
585 If the "Algorithm::DiffOld" package is installed on the local
587 system, output describing the differences between the input lines
588 and the matching lines, in diff(1) format, is saved to the $output
589 array reference. In the diff output, the expected output lines are
590 considered the "old" (left-hand) file, and the actual output is
591 considered the "new" (right-hand) file.
592 If the "Algorithm::DiffOld" package is not installed on the local
594 system, the Expected and Actual contents are saved as-is to the
595 $output array reference.
596 The "lines" and "regexes" arguments are passed in as either
598 scalars, in which case each is split on newline boundaries, or as
599 array references. Trailing newlines are stripped from each line
600 and regular expression. Comparison is performed for each entire
601 line, that is, with each regular expression anchored at both the
602 start of line (^) and end of line ($).
603 Returns TRUE if each line matched each regular expression, FALSE
605 otherwise, in order to conform to the conventions of the "match"
606 method.
607 Typical invocation:
609 if (! $test->diff_regex($test->stdout,
611 \@expected_lines,
612 \@diff)) {
613 print @diff;
614 }
615 "match_sub"
617 Registers the specified code reference as the line-matching
618 function to be called by the "match" method. This can be a user-
619 supplied subroutine, or the "match_exact", "match_regex",
620 "diff_exact", or "diff_regex" methods supplied by the "Test::Cmd"
621 module:
622 $test->match_sub(\&Test::Cmd::match_exact);
624 $test->match_sub(\&Test::Cmd::match_regex);
626 $test->match_sub(\&Test::Cmd::diff_exact);
628 $test->match_sub(\&Test::Cmd::diff_regex);
630 The "match_exact", "match_regex", "diff_exact" and "diff_regex"
632 subroutine names are exportable from the "Test::Cmd" module, and
633 may be specified at object initialization:
634 use Test::Cmd qw(match_exact match_regex diff_exact diff_regex);
636 $test_exact = Test::Cmd->new(match_sub => \&match_exact);
637 $test_regex = Test::Cmd->new(match_sub => \&match_regex);
638 $test_exact = Test::Cmd->new(match_sub => \&diff_exact);
639 $test_regex = Test::Cmd->new(match_sub => \&diff_regex);
640 "here"
642 Returns the absolute path name of the current working directory.
643 (This is essentially the same as the "Cwd::cwd" method, except that
644 the "Test::Cmd::here" method preserves the directory separators
645 exactly as returned by the underlying operating-system-dependent
646 method. The "Cwd::cwd" method canonicalizes all directory
647 separators to '/', which makes for consistent path name
648 representations within Perl, but may mess up another program or
649 script to which you try to pass the path name.)
650
652 Several environment variables affect the default values in a newly
653 created "Test::Cmd" environment object. These environment variables
654 must be set when the module is loaded, not when the object is created.
655 "PRESERVE"
657 If set to a true value, all temporary working directories will be
658 preserved on exit, regardless of success or failure of the test.
659 The full path names of all temporary working directories will be
660 reported on error output.
661 "PRESERVE_FAIL"
663 If set to a true value, all temporary working directories will be
664 preserved on exit from a failed test. The full path names of all
665 temporary working directories will be reported on error output.
666 "PRESERVE_NO_RESULT"
668 If set to a true value, all temporary working directories will be
669 preserved on exit from a test for which there is no result. The
670 full path names of all temporary working directories will be
671 reported on error output.
672 "PRESERVE_PASS"
674 If set to a true value, all temporary working directories will be
675 preserved on exit from a successful test. The full path names of
676 all temporary working directories will be reported on error output.
677 "VERBOSE"
679 When set to a true value, enables verbose reporting of various
680 internal things (path names, exact command line being executed,
681 etc.).
682
684 Although the "Test::Cmd" module is intended to make it easier to write
685 portable tests for portable utilities that interact with file systems,
686 it is still very easy to write non-portable tests if you're not
687 careful.
688 The best and most comprehensive set of portability guidelines is the
690 standard "Writing portable Perl" document at:
691 http://www.perl.com/pub/doc/manual/html/pod/perlport.html
693 To reiterate one important point from the "WpP" document: Not all Perl
695 programs have to be portable. If the program or script you're testing
696 is UNIX-specific, you can (and should) use the "Test::Cmd" module to
697 write UNIX-specific tests.
698 That having been said, here are some hints that may help keep your
700 tests portable, if that's a requirement.
701 Use the "Test::Cmd-&"here> method for current directory path.
703 The normal Perl way to fetch the current working directory is to
704 use the "Cwd::cwd" method. Unfortunately, the "Cwd::cwd" method
705 canonicalizes the path name it returns, changing the native
706 directory separators into the forward slashes favored by Perl and
707 UNIX. For most Perl scripts, this makes a great deal of sense and
708 keeps code uncluttered.
709 Passing in a file name that has had its directory separators
711 altered, however, may confuse the command or script under test, or
712 make it difficult to compare output from the command or script with
713 an expected result. The "Test::Cmd::here" method returns the
714 absolute path name of the current working directory, like
715 "Cwd::cwd", but does not manipulate the returned path in any way.
716 Use "File::Spec" methods for manipulating path names.
718 The "File::Spec" module provides a system-independent interface for
719 manipulating path names. Because the "Test::Cmd" class is a sub-
720 class of the "File::Spec" class, you can use these methods directly
721 as follows:
722 if (! Test::Cmd->file_name_is_absolute($prog)) {
724 my $prog = Test::Cmd->catfile(Test::Cmd->here, $prog);
725 }
726 For details about the available methods and their use, see the
728 documentation for the "File::Spec" module and its sub-modules,
729 especially the "File::Spec::Unix" modules.
730 Use "Config" for file-name suffixes, where possible.
732 The standard "Config" module provides values that reflect the file-
733 name suffixes on the system for which the Perl executable was
734 built. This provides convenient portability for situations where a
735 file name may have different extensions on different systems:
736 $foo_exe = "foo$Config{_exe}";
738 ok(-f $foo_exe);
739 (Unfortunately, there is no existing $Config value that specifies
741 the suffix for a directly-executable Perl script.)
742 Avoid generating executable programs or scripts.
744 How to make a file or script executable varies widely from system
745 to system, some systems using file name extensions to indicate
746 executability, others using a file permission bit. The differences
747 are complicated to accomodate in a portable test script. The
748 easiest way to deal with this complexity is to avoid it if you can.
749 If your test somehow requires executing a script that you generate
751 from the test itself, the best way is to generate the script in
752 Perl and then explicitly feed it to the Perl executable on the
753 local system. To be maximally portable, use the $^X variable
754 instead of hard-coding "perl" into the string you execute:
755 $line = "This is output from the generated perl script.";
757 $test->write('script', <<EOF);
758 print STDOUT "$line\\n";
759 EOF
760 $output = `$^X script`;
761 ok($output eq "$line\n");
762 This completely avoids having to make the "script" file itself
764 executable. (Since you're writing your test in Perl, it's safe to
765 assume that Perl itself is executable.)
766 If you must generate a directly-executable script, then use the
768 $Config{'startperl'} variable at the start of the script to
769 generate the appropriate magic that will execute it as a Perl
770 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
799 number of end-to-end application tests. The suite, and other
800 information 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
835 multiple testing frameworks.
836
838 Hey! The above document had some coding errors, which are explained
839 below:
840 Around line 1609:
842 =back doesn't take any parameters, but you said =back 4
843perl v5.12.0 2001-09-05 Cmd(3)