1Test::Cmd::Common(3) User Contributed Perl Documentation Test::Cmd::Common(3)
2
6 Test::Cmd::Common - module for common Test::Cmd error handling
7
9 use Test::Cmd::Common;
10 $test = Test::Cmd::Common->new(string => 'functionality being tested',
12 prog => 'program_under_test',
13 );
14 $test->run(chdir => 'subdir', fail => '$? != 0',
16 flags => '-x', targets => '.',
17 stdout => <<_EOF_, stderr => <<_EOF_);
18 expected standard output
19 _EOF_
20 expected error output
21 _EOF_
22 $test->subdir('subdir', ...);
24 $test->read(\$contents, 'file');
26 $test->read(\@lines, 'file');
27 $test->write('file', <<_EOF_);
29 contents of the file
30 _EOF_
31 $test->file_matches();
33 $test->must_exist('file', ['subdir', 'file'], ...);
35 $test->must_not_exist('file', ['subdir', 'file'], ...);
37 $test->copy('src_file', 'dst_file');
39 $test->chmod($mode, 'file', ...);
41 $test->sleep;
43 $test->sleep($seconds);
44 $test->touch('file', ...);
46 $test->unlink('file', ...);
48
50 The "Test::Cmd::Common" module provides a simple, high-level interface
51 for writing tests of executable commands and scripts, especially
52 commands and scripts that interact with the file system. All methods
53 throw exceptions and exit on failure. This makes it unnecessary to add
54 explicit checks for return values, making the test scripts themselves
55 simpler to write and easier to read.
56 The "Test::Cmd::Common" class is a subclass of Test::Cmd. In essence,
58 "Test::Cmd::Common" is a wrapper that treats common Test::Cmd error
59 conditions as exceptions that terminate the test. You can use
60 "Test::Cmd::Common" directly, or subclass it for your program and add
61 additional (or override) methods to tailor it to your program's
62 specific needs. Alternatively, "Test::Cmd::Common" serves as a useful
63 example of how to define your own Test::Cmd subclass.
64 The "Test::Cmd::Common" module provides the following importable
66 variables:
67 $_exe
69 The executable file suffix. This value is normally available as
70 $Config{_exe} in Perl version 5.005 and later. The
71 "Test::Cmd::Common" module figures it out via other means in
72 earlier versions.
73 $_o The object file suffix. This value is normally available from
75 $Config{_o} in Perl version 5.005 and later. The
76 "Test::Cmd::Common" module figures it out via other means in
77 earlier versions.
78 $_a The library file suffix. This value is normally available from as
80 $Config{_a} in Perl version 5.005 and later. The
81 "Test::Cmd::Common" module figures it out via other means in
82 earlier versions.
83 $_so
85 The shared library file suffix. This value is normally available
86 as $Config{_so} in Perl version 5.005 and later. The
87 "Test::Cmd::Common" module figures it out via other means in
88 earlier versions.
89 $_is_win32
91 A Boolean value that reflects whether the current platform is a
92 Win32 system.
93
95 "new"
96 Creates a new test environment object. Any arguments are keyword-
97 value pairs that are passed through to the construct method for the
98 base class from which we inherit our methods (that is, the
99 Test::Cmd class). In the normal case, this should be the program
100 to be tested and a description of the functionality being tested:
101 $test = Test::Cmd::Common->new(prog => 'my_program',
103 string => 'cool new feature');
104 By default, methods that match actual versus expected output (the
106 "run", and "file_matches" methods) use an exact match. Tests that
107 require regular expression matches can specify this on
108 initialization of the test environment:
109 $test = Test::Cmd::Common->new(prog => 'my_program',
111 string => 'cool new feature',
112 match_sub => \&Test::Cmd::diff_regex);
113 or by executing the following after initialization of the test
115 environment:
116 $test->match_sub(\&Test::Cmd::diff_regex);
118 Creates a temporary working directory for the test environment and
120 changes directory to it.
121 Exits NO RESULT if the object can not be created, the temporary
123 working directory can not be created, or the current directory
124 cannot be changed to the temporary working directory.
125 "run"
127 Runs the program under test, checking that the test succeeded.
128 Arguments are keyword-value pairs that affect the manner in which
129 the program is executed or the results are evaluated.
130 chdir => 'subdir'
132 fail => 'failure condition' # default is '$? != 0'
133 flags => 'Cons flags'
134 stderr => 'expected error output'
135 stdout => 'expected standard output'
136 targets => 'targets to build'
137 The test fails if:
139 -- The specified failure condition is met. The default failure
141 condition is '$? != 0', i.e. the program exits unsuccesfully.
142 A not-uncommon alternative is:
143 $test->run(fail => '$? == 0'); # expect failure
145 when testing how the program handles errors.
147 -- Actual standard output does not match expected standard output
149 (if any). The expected standard output is an array of lines
150 or a scalar which will be split on newlines.
151 -- Actual error output does not match expected error output (if
153 any). The expected error output is an array of lines or a
154 scalar which will be split on newlines.
155 This method will test for NO error output by default if no
157 expected error output is specified (unlike standard output).
158 The error output test may be explicitly suppressed by
159 specifying undef as the "expected" error output:
160 $test->run(stderr => undef);
162 By default, this method performs an exact match of actual vs.
164 expected standard output or error output:
165 $test->run(stdout => <<_EOF_, stderr => _EOF_);
167 An expected STDOUT line, which must be matched exactly.
168 _EOF_
169 One or more expected STDERR lines,
170 which must be matched exactly.
171 _EOF_
172 Tests that require regular expression matches should be executed
174 using a test environment that calls the "match_sub" method as
175 follows:
176 $test->match_sub(\&Test::Cmd::diff_regex);
178 $test->run(stdout => <<_EOF_, stderr => _EOF_);
180 An expected (STDOUT|standard output) line\.
181 _EOF_
182 One or more expected (STDERR|error output) lines,
183 which may contain (regexes|regular expressions)\.
184 _EOF_
185 "subdir"
187 Creates one or more subdirectories in the temporary working
188 directory. Exits NO RESULT if the number of subdirectories
189 actually created does not match the number expected. For
190 compatibility with its superclass method, returns the number of
191 subdirectories actually created.
192 "read"
194 Reads the contents of a file, depositing the contents in the
195 destination referred to by the first argument (a scalar or array
196 reference). If the file name is not an absolute path name, it is
197 relative to the temporary working directory. Exits NO RESULT if
198 the file could not be read for any reason. For compatibility with
199 its superclass method, returns TRUE on success.
200 "write"
202 Writes a file with the specified contents. If the file name is not
203 an absolute path name, it is relative to the temporary working
204 directory. Exits NO RESULT if there were any errors writing the
205 file. For compatibility with its superclass method, returns TRUE
206 on success.
207 $test->write('file', <<_EOF_);
209 contents of the file
210 _EOF_
211 "file_matches"
213 Matches the contents of the specified file (first argument) against
214 the expected contents. The expected contents are an array of lines
215 or a scalar which will be split on newlines. By default, each
216 expected line must match exactly its corresponding line in the
217 file:
218 $test->file_matches('file', <<_EOF_);
220 Line #1.
221 Line #2.
222 _EOF_
223 Tests that require regular expression matches should be executed
225 using a test environment that calls the "match_sub" method as
226 follows:
227 $test->match_sub(\&Test::Cmd::diff_regex);
229 $test->file_matches('file', <<_EOF_);
231 The (1st|first) line\.
232 The (2nd|second) line\.
233 _EOF_
234 "must_exist"
236 Ensures that the specified files must exist. Files may be
237 specified as an array reference of directory components, in which
238 case the pathname will be constructed by concatenating them. Exits
239 FAILED if any of the files does not exist.
240 "must_not_exist"
242 Ensures that the specified files must not exist. Files may be
243 specified as an array reference of directory components, in which
244 case the pathname will be constructed by concatenating them. Exits
245 FAILED if any of the files exists.
246 "copy"
248 Copies a file from the source (first argument) to the destination
249 (second argument). Exits NO RESULT if the file could not be copied
250 for any reason.
251 "chmod"
253 Changes the permissions of a list of files to the specified mode
254 (first argument). Exits NO RESULT if any file could not be changed
255 for any reason.
256 "sleep"
258 Sleeps at least the specified number of seconds. If no number is
259 specified, sleeps at least a minimum number of seconds necessary to
260 advance file time stamps on the current system. Sleeping more
261 seconds is all right. Exits NO RESULT if the time slept was less
262 than specified.
263 "touch"
265 Updates the access and modification times of the specified files.
266 Exits NO RESULT if any file could not be modified for any reason.
267 "unlink"
269 Removes the specified files. Exits NO RESULT if any file could not
270 be removed for any reason.
271
273 The "Test::Cmd::Common" module also uses the "PRESERVE",
274 "PRESERVE_FAIL", "PRESERVE_NO_RESULT", and "PRESERVE_PASS" environment
275 variables from the Test::Cmd module. See the Test::Cmd documentation
276 for details.
277
279 perl(1), Test::Cmd.
280 The most involved example of using the "Test::Cmd::Common" module to
282 test a real-world application is the "cons-test" testing suite for the
283 Cons software construction utility. The suite sub-classes
284 "Test::Cmd::Common" to provide common, application-specific
285 infrastructure across a large number of end-to-end application tests.
286 The suite, and other information about Cons, is available at:
287 http://www.dsmit.com/cons
289
291 Steven Knight, knight@baldmt.com
292
294 Thanks to Johan Holmberg for asking the question that led to the
295 creation of this package.
296 The general idea of testing commands in this way, as well as the test
298 reporting of the "pass", "fail" and "no_result" methods, come from the
299 testing framework invented by Peter Miller for his Aegis project change
300 supervisor. Aegis is an excellent bit of work which integrates
301 creation and execution of regression tests into the software
302 development process. Information about Aegis is available at:
303 http://www.tip.net.au/~millerp/aegis.html
305perl v5.36.0 2022-07-22 Test::Cmd::Common(3)