1Test::Cmd(3) User Contributed Perl Documentation Test::Cmd(3)
2
6 Test::Cmd - Perl module for portable testing of commands and scripts
7
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 use Test::Cmd;
13 use Test::More tests => 3;
14 my $test = Test::Cmd->new( prog => 'outerr', workdir => '' );
16 $test->run();
17 is( $test->stdout, "out\n", 'standard out' );
19 is( $test->stderr, "err\n", 'standard error' );
20 is( $? >> 8, 1, 'exit status' );
21 Where "outerr" is the shell script:
23 $ cat outerr
25 #!/bin/sh
26 echo out
27 echo >&2 err
28 exit 1
29 $ chmod +x outerr
30 See below for other examples. Otherwise, the full list of available
32 methods is:
33 use Test::Cmd;
35 $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 $test->verbose(1);
45 $test->prog('program_or_script_to_test');
47 $test->basename(@suffixlist);
49 $test->interpreter('script_interpreter');
51 $test->string('identifier string');
53 $test->workdir('prefix');
55 $test->workpath('subdir', 'file');
57 $test->subdir('subdir', ...);
59 $test->subdir(['sub', 'dir'], ...);
60 $test->write('file', <<'EOF');
62 contents of file
63 EOF
64 $test->write(['subdir', 'file'], <<'EOF');
65 contents of file
66 EOF
67 $test->read(\$contents, 'file');
69 $test->read(\@lines, 'file');
70 $test->read(\$contents, ['subdir', 'file']);
71 $test->read(\@lines, ['subdir', 'file']);
72 $test->writable('dir');
74 $test->writable('dir', $rwflag);
75 $test->writable('dir', $rwflag, \%errors);
76 $test->preserve(condition, ...);
78 $test->cleanup(condition);
80 $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 $test->pass(condition);
88 $test->pass(condition, \&func);
89 $test->fail(condition);
91 $test->fail(condition, \&func);
92 $test->fail(condition, \&func, $caller);
93 $test->no_result(condition);
95 $test->no_result(condition, \&func);
96 $test->no_result(condition, \&func, $caller);
97 $test->stdout;
99 $test->stdout($run_number);
100 $test->stderr;
102 $test->stderr($run_number);
103 $test->match(\@lines, \@matches);
105 $test->match($lines, $matches);
106 $test->match_exact(\@lines, \@matches);
108 $test->match_exact($lines, $matches);
109 $test->match_regex(\@lines, \@regexes);
111 $test->match_regex($lines, $regexes);
112 $test->diff_exact(\@lines, \@matches, \@output);
114 $test->diff_exact($lines, $matches, \@output);
115 $test->diff_regex(\@lines, \@regexes, \@output);
117 $test->diff_regex($lines, $regexes, \@output);
118 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 $test->here;
127
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 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 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 (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 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 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 A "Test::Cmd" environment object is created via the usual invocation:
164 $test = Test::Cmd->new();
166 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
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 Note that you should not intermix multiple testing frameworks in a
180 single testing script.
181 "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 use Test::Cmd;
187 print "1..5\n";
189 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
191 if ($test) { print "ok 1\n"; } else { print "not ok 1\n"; }
192 $input = <<_EOF;
194 test_program should process this input
195 and exit successfully (status 0).
196 _EOF_
197 $wrote_file = $test->write('input_file', $input);
199 if ($wrote_file) { print "ok 2\n"; } else { print "not ok 2\n"; }
200 $test->run(args => '-x input_file');
202 if ($? == 0) { print "ok 3\n"; } else { print "not ok 3\n"; }
203 $wrote_file = $test->write('input_file', $input);
205 if ($wrote_file) { print "ok 4\n"; } else { print "not ok 4\n"; }
206 $test->run(args => '-y input_file');
208 if ($? == 0) { print "ok 5\n"; } else { print "not ok 5\n"; }
209 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 use Test::Simple tests => 5;
217 use Test::Cmd;
218 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
220 ok($test, "creating Test::Cmd object");
221 $input = <<_EOF;
223 test_program should process this input
224 and exit successfully (status 0).
225 _EOF_
226 $wrote_file = $test->write('input_file', $input);
228 ok($wrote_file, "writing input_file");
229 $test->run(args => '-x input_file');
231 ok($? == 0, "executing test_program -x input_file");
232 $wrote_file = $test->write('input_file', $input);
234 ok($wrote_file, "writing input_file");
235 $test->run(args => '-y input_file');
237 ok($? == 0, "executing test_program -y input_file");
238 "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 use Test::Unit;
248 use Test::Cmd;
249 my $test;
251 $input = <<'EOF';
253 test_program should process this input
254 and exit successfully (status 0).
255 EOF
256 sub set_up {
258 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
259 $test->write('input_file', $input);
260 }
261 sub test_x {
263 my $result = $test->run(args => '-x input_file');
264 assert($result == 0, "failed test_x\n");
265 }
266 sub test_y {
268 my $result = $test->run(args => '-y input_file');
269 assert($result == 0, "failed test_y\n");
270 }
271 create_suite();
273 run_suite;
274 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 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 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 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 use Test::Cmd;
300 $test = Test::Cmd->new(prog => 'test_program', workdir => '');
302 Test::Cmd->no_result(! $test);
303 $input = <<EOF;
305 test_program should process this input
306 and exit successfully (status 0).
307 EOF
308 $wrote_file = $test->write('input_file', $input);
310 $test->no_result(! $wrote_file);
311 $test->run(args => '-x input_file');
313 $test->fail($? != 0);
314 $wrote_file = $test->write('input_file', $input);
316 $test->no_result(! $wrote_file);
317 $test->run(args => '-y input_file');
319 $test->fail($? != 0);
320 $test->pass;
322 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 use Test::Cmd::Common;
328 $test = Test::Cmd::Common->new(prog => 'test_program', workdir => '');
330 $input = <<EOF;
332 test_program should process this input
333 and exit successfully (status 0).
334 EOF
335 $wrote_file = $test->write('input_file', $input);
337 $test->run(args => '-x input_file');
339 $wrote_file = $test->write('input_file', $input);
341 $test->run(args => '-y input_file');
343 $test->pass;
345 See the Test::Cmd::Common module for details.
347
349 Methods supported by the "Test::Cmd" module include:
350 "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 "verbose"
359 Sets the verbose level for the environment object to the specified
360 value.
361 "prog"
363 Specifies the executable program or script to be tested. Returns
364 the absolute path name of the current program or script.
365 "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 "interpreter"
372 Specifies the program to be used to interpret "prog" as a script.
373 Returns the current value of "interpreter".
374 "string"
376 Specifies an identifier string for the functionality being tested
377 to be printed on failure or no result.
378 "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 Returns the absolute pathname to the temporary working directory,
386 or FALSE if the directory could not be created.
387 "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 "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 $test->subdir('sub', ['sub', 'dir'], [qw(sub dir ectory)]);
401 Returns the number of subdirectories actually created.
403 "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 "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 Returns TRUE on successfully opening and reading the file, FALSE
421 otherwise.
422 "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 "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 "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 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 "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 Arguments are supplied as keyword-value pairs:
458 "args"
460 Specifies the command-line arguments to be supplied to the
461 program or script under test for this run:
462 $test->run(args => 'arg1 arg2');
464 "chdir"
466 Changes directory to the path specified as the value argument:
467 $test->run(chdir => 'xyzzy');
469 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 $test->run(chdir => '.'); # Unix-specific
479 $test->run(chdir => $test->curdir); # portable
481 "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 "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 "stdin"
493 Pipes the specified value (string or array ref) to the program
494 or script under test for this run:
495 $test->run(stdin => <<_EOF_);
497 input to the program under test
498 _EOF_
499 Returns the exit status of the program or script.
501 "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 "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 "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 "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 "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 "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 "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 Returns TRUE if each line matched its corresponding line in the
558 other array, FALSE otherwise.
559 "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 Returns TRUE if each line matched each regular expression, FALSE
572 otherwise.
573 "diff_exact"
575 Diffs two arrays of lines in a manner similar to the UNIX diff(1)
576 utility.
577 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 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 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 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 Typical invocation:
599 if (! $test->diff_exact($test->stdout,
601 \@expected_lines,
602 \@diff)) {
603 print @diff;
604 }
605 "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 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 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 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 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 Typical invocation:
633 if (! $test->diff_regex($test->stdout,
635 \@expected_lines,
636 \@diff)) {
637 print @diff;
638 }
639 "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 $test->match_sub(\&Test::Cmd::match_exact);
648 $test->match_sub(\&Test::Cmd::match_regex);
650 $test->match_sub(\&Test::Cmd::diff_exact);
652 $test->match_sub(\&Test::Cmd::diff_regex);
654 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 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 "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
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 "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 "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 "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 "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 "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
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 The best and most comprehensive set of portability guidelines is the
714 standard "Writing portable Perl" document at:
715 http://www.perl.com/pub/doc/manual/html/pod/perlport.html
717 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 That having been said, here are some hints that may help keep your
724 tests portable, if that's a requirement.
725 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 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 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 if (! Test::Cmd->file_name_is_absolute($prog)) {
748 my $prog = Test::Cmd->catfile(Test::Cmd->here, $prog);
749 }
750 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 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 $foo_exe = "foo$Config{_exe}";
762 ok(-f $foo_exe);
763 (Unfortunately, there is no existing $Config value that specifies
765 the suffix for a directly-executable Perl script.)
766 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 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 $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 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 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 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 Addtional hints on writing portable tests are welcome.
808
810 perl(1), Algorithm::DiffOld, File::Find, File::Spec, Test,
811 Test::Cmd::Common, Test::Harness, Test::More, Test::Simple, Test::Unit.
812 Alternative command-testing modules include:
814 Test::Exit, Test::Output, or using Capture::Tiny with one of the above
816 test modules, for example Test::More.
817 A rudimentary page for the "Test::Cmd" module is available at:
819 http://www.baldmt.com/Test-Cmd/
821 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 http://www.dsmit.com/cons
831
833 <https://github.com/neilb/Test-Cmd>
834
836 Steven Knight, knight@baldmt.com
837 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
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 http://www.dsmit.com/cons/
852 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 http://www.tip.net.au/~millerp/aegis.html
861 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.
869perl v5.36.0 2023-01-20 Test::Cmd(3)