Test::Common(3pm)

1Common(3)             User Contributed Perl Documentation            Common(3)
2
3
4

NAME

6       Test::Cmd::Common - module for common Test::Cmd error handling
7

SYNOPSIS

9         use Test::Cmd::Common;
10
11         $test = Test::Cmd::Common->new(string => 'functionality being tested',
12                               prog => 'program_under_test',
13                               );
14
15         $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
23         $test->subdir('subdir', ...);
24
25         $test->read(\$contents, 'file');
26         $test->read(\@lines, 'file');
27
28         $test->write('file', <<_EOF_);
29         contents of the file
30         _EOF_
31
32         $test->file_matches();
33
34         $test->must_exist('file', ['subdir', 'file'], ...);
35
36         $test->must_not_exist('file', ['subdir', 'file'], ...);
37
38         $test->copy('src_file', 'dst_file');
39
40         $test->chmod($mode, 'file', ...);
41
42         $test->sleep;
43         $test->sleep($seconds);
44
45         $test->touch('file', ...);
46
47         $test->unlink('file', ...);
48

DESCRIPTION

50       The "Test::Cmd::Common" module provides a simple, high-level interface
51       for writing tests of executable commands and scripts, especially com‐
52       mands 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
57       The "Test::Cmd::Common" class is a subclass of "Test::Cmd".  In
58       essence, "Test::Cmd::Common" is a wrapper that treats common
59       "Test::Cmd" error conditions as exceptions that terminate the test.
60       You can use "Test::Cmd::Common" directly, or subclass it for your pro‐
61       gram and add additional (or override) methods to tailor it to your pro‐
62       gram's specific needs.  Alternatively, "Test::Cmd::Common" serves as a
63       useful example of how to define your own "Test::Cmd" subclass.
64
65       The "Test::Cmd::Common" module provides the following importable vari‐
66       ables:
67
68       $_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 ear‐
72           lier versions.
73
74       $_o The object file suffix.  This value is normally available from
75           $Config{_o} in Perl version 5.005 and later.  The "Test::Cmd::Com‐
76           mon" module figures it out via other means in earlier versions.
77
78       $_a The library file suffix.  This value is normally available from as
79           $Config{_a} in Perl version 5.005 and later.  The "Test::Cmd::Com‐
80           mon" module figures it out via other means in earlier versions.
81
82       $_so
83           The shared library file suffix.  This value is normally available
84           as $Config{_so} in Perl version 5.005 and later.  The
85           "Test::Cmd::Common" module figures it out via other means in ear‐
86           lier versions.
87
88       $_is_win32
89           A Boolean value that reflects whether the current platform is a
90           Win32 system.
91

METHODS

93       "new"
94           Creates a new test environment object.  Any arguments are keyword-
95           value pairs that are passed through to the construct method for the
96           base class from which we inherit our methods (that is, the
97           "Test::Cmd" class).  In the normal case, this should be the program
98           to be tested and a description of the functionality being tested:
99
100               $test = Test::Cmd::Common->new(prog => 'my_program',
101                                              string => 'cool new feature');
102
103           By default, methods that match actual versus expected output (the
104           "run", and "file_matches" methods) use an exact match.  Tests that
105           require regular expression matches can specify this on initializa‐
106           tion of the test environment:
107
108               $test = Test::Cmd::Common->new(prog => 'my_program',
109                                              string => 'cool new feature',
110                                              match_sub => \&Test::Cmd::diff_regex);
111
112           or by executing the following after initialization of the test
113           environment:
114
115               $test->match_sub(\&Test::Cmd::diff_regex);
116
117           Creates a temporary working directory for the test environment and
118           changes directory to it.
119
120           Exits NO RESULT if the object can not be created, the temporary
121           working directory can not be created, or the current directory can‐
122           not be changed to the temporary working directory.
123
124       "run"
125           Runs the program under test, checking that the test succeeded.
126           Arguments are keyword-value pairs that affect the manner in which
127           the program is executed or the results are evaluated.
128
129               chdir => 'subdir'
130               fail => 'failure condition' # default is '$? != 0'
131               flags => 'Cons flags'
132               stderr => 'expected error output'
133               stdout => 'expected standard output'
134               targets => 'targets to build'
135
136           The test fails if:
137
138             --  The specified failure condition is met.  The default failure
139                 condition is '$? != 0', i.e. the program exits unsuccesfully.
140                 A not-uncommon alternative is:
141
142                     $test->run(fail => '$? == 0');        # expect failure
143
144                 when testing how the program handles errors.
145
146             --  Actual standard output does not match expected standard output
147                 (if any).  The expected standard output is an array of lines
148                 or a scalar which will be split on newlines.
149
150             --  Actual error output does not match expected error output (if
151                 any).  The expected error output is an array of lines or a
152                 scalar which will be split on newlines.
153
154                 This method will test for NO error output by default if no
155                 expected error output is specified (unlike standard output).
156                 The error output test may be explicitly suppressed by
157                 specifying undef as the "expected" error output:
158
159                     $test->run(stderr => undef);
160
161           By default, this method performs an exact match of actual vs.
162           expected standard output or error output:
163
164               $test->run(stdout => <<_EOF_, stderr => _EOF_);
165               An expected STDOUT line, which must be matched exactly.
166               _EOF_
167               One or more expected STDERR lines,
168               which must be matched exactly.
169               _EOF_
170
171           Tests that require regular expression matches should be executed
172           using a test environment that calls the "match_sub" method as fol‐
173           lows:
174
175               $test->match_sub(\&Test::Cmd::diff_regex);
176
177               $test->run(stdout => <<_EOF_, stderr => _EOF_);
178               An expected (STDOUT⎪standard output) line\.
179               _EOF_
180               One or more expected (STDERR⎪error output) lines,
181               which may contain (regexes⎪regular expressions)\.
182               _EOF_
183
184       "subdir"
185           Creates one or more subdirectories in the temporary working direc‐
186           tory.  Exits NO RESULT if the number of subdirectories actually
187           created does not match the number expected.  For compatibility with
188           its superclass method, returns the number of subdirectories actu‐
189           ally created.
190
191       "read"
192           Reads the contents of a file, depositing the contents in the desti‐
193           nation referred to by the first argument (a scalar or array refer‐
194           ence).  If the file name is not an absolute path name, it is rela‐
195           tive to the temporary working directory.  Exits NO RESULT if the
196           file could not be read for any reason.  For compatibility with its
197           superclass method, returns TRUE on success.
198
199       "write"
200           Writes a file with the specified contents.  If the file name is not
201           an absolute path name, it is relative to the temporary working
202           directory.  Exits NO RESULT if there were any errors writing the
203           file.  For compatibility with its superclass method, returns TRUE
204           on success.
205
206               $test->write('file', <<_EOF_);
207               contents of the file
208               _EOF_
209
210       "file_matches"
211           Matches the contents of the specified file (first argument) against
212           the expected contents.  The expected contents are an array of lines
213           or a scalar which will be split on newlines.  By default, each
214           expected line must match exactly its corresponding line in the
215           file:
216
217               $test->file_matches('file', <<_EOF_);
218               Line #1.
219               Line #2.
220               _EOF_
221
222           Tests that require regular expression matches should be executed
223           using a test environment that calls the "match_sub" method as fol‐
224           lows:
225
226               $test->match_sub(\&Test::Cmd::diff_regex);
227
228               $test->file_matches('file', <<_EOF_);
229               The (1st⎪first) line\.
230               The (2nd⎪second) line\.
231               _EOF_
232
233       "must_exist"
234           Ensures that the specified files must exist.  Files may be speci‐
235           fied as an array reference of directory components, in which case
236           the pathname will be constructed by concatenating them.  Exits
237           FAILED if any of the files does not exist.
238
239       "must_not_exist"
240           Ensures that the specified files must not exist.  Files may be
241           specified as an array reference of directory components, in which
242           case the pathname will be constructed by concatenating them.  Exits
243           FAILED if any of the files exists.
244
245       "copy"
246           Copies a file from the source (first argument) to the destination
247           (second argument).  Exits NO RESULT if the file could not be copied
248           for any reason.
249
250       "chmod"
251           Changes the permissions of a list of files to the specified mode
252           (first argument).  Exits NO RESULT if any file could not be changed
253           for any reason.
254
255       "sleep"
256           Sleeps at least the specified number of seconds.  If no number is
257           specified, sleeps at least a minimum number of seconds necessary to
258           advance file time stamps on the current system.  Sleeping more sec‐
259           onds is all right.  Exits NO RESULT if the time slept was less than
260           specified.
261
262       "touch"
263           Updates the access and modification times of the specified files.
264           Exits NO RESULT if any file could not be modified for any reason.
265
266       "unlink"
267           Removes the specified files.  Exits NO RESULT if any file could not
268           be removed for any reason.
269

ENVIRONMENT

271       The "Test::Cmd::Common" module also uses the "PRESERVE", "PRE‐
272       SERVE_FAIL", "PRESERVE_NO_RESULT", and "PRESERVE_PASS" environment
273       variables from the "Test::Cmd" module.  See the "Test::Cmd" documenta‐
274       tion for details.
275

AUTHOR

289       Steven Knight, knight@baldmt.com
290

ACKNOWLEDGEMENTS

292       Thanks to Johan Holmberg for asking the question that led to the cre‐
293       ation of this package.
294
295       The general idea of testing commands in this way, as well as the test
296       reporting of the "pass", "fail" and "no_result" methods, come from the
297       testing framework invented by Peter Miller for his Aegis project change
298       supervisor.  Aegis is an excellent bit of work which integrates cre‐
299       ation and execution of regression tests into the software development
300       process.  Information about Aegis is available at:
301
302               http://www.tip.net.au/~millerp/aegis.html
303
304
305
306perl v5.8.8                       2001-09-05                         Common(3)