Test::Cmd::Common(3pm)

1Test::Cmd::Common(3)  User Contributed Perl Documentation Test::Cmd::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
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
57       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
65       The "Test::Cmd::Common" module provides the following importable
66       variables:
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
72           earlier 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
76           "Test::Cmd::Common" module figures it out via other means in
77           earlier versions.
78
79       $_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
84       $_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
90       $_is_win32
91           A Boolean value that reflects whether the current platform is a
92           Win32 system.
93

METHODS

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
102               $test = Test::Cmd::Common->new(prog => 'my_program',
103                                              string => 'cool new feature');
104
105           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
110               $test = Test::Cmd::Common->new(prog => 'my_program',
111                                              string => 'cool new feature',
112                                              match_sub => \&Test::Cmd::diff_regex);
113
114           or by executing the following after initialization of the test
115           environment:
116
117               $test->match_sub(\&Test::Cmd::diff_regex);
118
119           Creates a temporary working directory for the test environment and
120           changes directory to it.
121
122           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
126       "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
131               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
138           The test fails if:
139
140             --  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
144                     $test->run(fail => '$? == 0');        # expect failure
145
146                 when testing how the program handles errors.
147
148             --  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
152             --  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
156                 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
161                     $test->run(stderr => undef);
162
163           By default, this method performs an exact match of actual vs.
164           expected standard output or error output:
165
166               $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
173           Tests that require regular expression matches should be executed
174           using a test environment that calls the "match_sub" method as
175           follows:
176
177               $test->match_sub(\&Test::Cmd::diff_regex);
178
179               $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
186       "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
193       "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
201       "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
208               $test->write('file', <<_EOF_);
209               contents of the file
210               _EOF_
211
212       "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
219               $test->file_matches('file', <<_EOF_);
220               Line #1.
221               Line #2.
222               _EOF_
223
224           Tests that require regular expression matches should be executed
225           using a test environment that calls the "match_sub" method as
226           follows:
227
228               $test->match_sub(\&Test::Cmd::diff_regex);
229
230               $test->file_matches('file', <<_EOF_);
231               The (1st|first) line\.
232               The (2nd|second) line\.
233               _EOF_
234
235       "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
241       "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
247       "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
252       "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
257       "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
264       "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
268       "unlink"
269           Removes the specified files.  Exits NO RESULT if any file could not
270           be removed for any reason.
271

ENVIRONMENT

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

AUTHOR

291       Steven Knight, knight@baldmt.com
292

ACKNOWLEDGEMENTS

294       Thanks to Johan Holmberg for asking the question that led to the
295       creation of this package.
296
297       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
304               http://www.tip.net.au/~millerp/aegis.html
305
306
307
308perl v5.38.0                      2023-07-21              Test::Cmd::Common(3)