1Apache::TestUtil(3) User Contributed Perl Documentation Apache::TestUtil(3)
2
6 Apache::TestUtil - Utility functions for writing tests
7
9 use Apache::Test;
10 use Apache::TestUtil;
11 ok t_cmp("foo", "foo", "sanity check");
13 t_write_file("filename", @content);
14 my $fh = t_open_file($filename);
15 t_mkdir("/foo/bar");
16 t_rmtree("/foo/bar");
17 t_is_equal($a, $b);
18
20 "Apache::TestUtil" automatically exports a number of functions useful
21 in writing tests.
22 All the files and directories created using the functions from this
24 package will be automatically destroyed at the end of the program exe‐
25 cution (via END block). You should not use these functions other than
26 from within tests which should cleanup all the created directories and
27 files at the end of the test.
28
30 t_cmp()
31 t_cmp($received, $expected, $comment);
32 t_cmp() prints the values of $comment, $expected and $received.
34 e.g.:
35 t_cmp(1, 1, "1 == 1?");
37 prints:
39 # testing : 1 == 1?
41 # expected: 1
42 # received: 1
43 then it returns the result of comparison of the $expected and the
45 $received variables. Usually, the return value of this function is
46 fed directly to the ok() function, like this:
47 ok t_cmp(1, 1, "1 == 1?");
49 the third argument ($comment) is optional, mostly useful for
51 telling what the comparison is trying to do.
52 It is valid to use "undef" as an expected value. Therefore:
54 my $foo;
56 t_cmp(undef, $foo, "undef == undef?");
57 will return a true value.
59 You can compare any two data-structures with t_cmp(). Just make
61 sure that if you pass non-scalars, you have to pass their refer‐
62 ences. The datastructures can be deeply nested. For example you can
63 compare:
64 t_cmp({1 => [2..3,{5..8}], 4 => [5..6]},
66 {1 => [2..3,{5..8}], 4 => [5..6]},
67 "hash of array of hashes");
68 You can also compare the second argument against the first as a
70 regex. Use the "qr//" function in the second argument. For example:
71 t_cmp("abcd", qr/^abc/, "regex compare");
73 will do:
75 "abcd" =~ /^abc/;
77 This function is exported by default.
79 t_filepath_cmp()
81 This function is used to compare two filepaths via t_cmp(). For
82 non-Win32, it simply uses t_cmp() for the comparison, but for
83 Win32, Win32::GetLongPathName() is invoked to convert the first two
84 arguments to their DOS long pathname. This is useful when there is
85 a possibility the two paths being compared are not both represented
86 by their long or short pathname.
87 This function is exported by default.
89 t_debug()
91 t_debug("testing feature foo");
92 t_debug("test", [1..3], 5, {a=>[1..5]});
93 t_debug() prints out any datastructure while prepending "#" at the
95 beginning of each line, to make the debug printouts comply with
96 "Test::Harness"'s requirements. This function should be always used
97 for debug prints, since if in the future the debug printing will
98 change (e.g. redirected into a file) your tests won't need to be
99 changed.
100 the special global variable $Apache::TestUtil::DEBUG_OUTPUT can be
102 used to redirect the output from t_debug() and related calls such
103 as t_write_file(). for example, from a server-side test you would
104 probably need to redirect it to STDERR:
105 sub handler {
107 plan $r, tests => 1;
108 local $Apache::TestUtil::DEBUG_OUTPUT = \*STDERR;
110 t_write_file('/tmp/foo', 'bar');
112 ...
113 }
114 left to its own devices, t_debug() will collide with the standard
116 HTTP protocol during server-side tests, resulting in a situation
117 both confusing difficult to debug. but STDOUT is left as the
118 default, since you probably don't want debug output under normal
119 circumstances unless running under verbose mode.
120 This function is exported by default.
122 t_write_file()
124 t_write_file($filename, @lines);
125 t_write_file() creates a new file at $filename or overwrites the
127 existing file with the content passed in @lines. If only the $file‐
128 name is passed, an empty file will be created.
129 If parent directories of $filename don't exist they will be
131 automagically created.
132 The generated file will be automatically deleted at the end of the
134 program's execution.
135 This function is exported by default.
137 t_append_file()
139 t_append_file($filename, @lines);
140 t_append_file() is similar to t_write_file(), but it doesn't clob‐
142 ber existing files and appends @lines to the end of the file. If
143 the file doesn't exist it will create it.
144 If parent directories of $filename don't exist they will be
146 automagically created.
147 The generated file will be registered to be automatically deleted
149 at the end of the program's execution, only if the file was created
150 by t_append_file().
151 This function is exported by default.
153 t_write_shell_script()
155 Apache::TestUtil::t_write_shell_script($filename, @lines);
156 Similar to t_write_file() but creates a portable shell/batch
158 script. The created filename is constructed from $filename and an
159 appropriate extension automatically selected according to the plat‐
160 form the code is running under.
161 It returns the extension of the created file.
163 t_write_perl_script()
165 Apache::TestUtil::t_write_perl_script($filename, @lines);
166 Similar to t_write_file() but creates a executable Perl script with
168 correctly set shebang line.
169 t_open_file()
171 my $fh = t_open_file($filename);
172 t_open_file() opens a file $filename for writing and returns the
174 file handle to the opened file.
175 If parent directories of $filename don't exist they will be
177 automagically created.
178 The generated file will be automatically deleted at the end of the
180 program's execution.
181 This function is exported by default.
183 t_mkdir()
185 t_mkdir($dirname);
186 t_mkdir() creates a directory $dirname. The operation will fail if
188 the parent directory doesn't exist.
189 If parent directories of $dirname don't exist they will be automag‐
191 ically created.
192 The generated directory will be automatically deleted at the end of
194 the program's execution.
195 This function is exported by default.
197 t_rmtree()
199 t_rmtree(@dirs);
200 t_rmtree() deletes the whole directories trees passed in @dirs.
202 This function is exported by default.
204 t_chown()
206 Apache::TestUtil::t_chown($file);
207 Change ownership of $file to the test's User/Group. This function
209 is noop on platforms where chown(2) is unsupported (e.g. Win32).
210 t_is_equal()
212 t_is_equal($a, $b);
213 t_is_equal() compares any two datastructures and returns 1 if they
215 are exactly the same, otherwise 0. The datastructures can be nested
216 hashes, arrays, scalars, undefs or a combination of any of these.
217 See t_cmp() for an example.
218 If $b is a regex reference, the regex comparison "$a =~ $b" is per‐
220 formed. For example:
221 t_is_equal($server_version, qr{^Apache});
223 If comparing non-scalars make sure to pass the references to the
225 datastructures.
226 This function is exported by default.
228 t_server_log_error_is_expected()
230 If the handler's execution results in an error or a warning logged
231 to the error_log file which is expected, it's a good idea to have a
232 disclaimer printed before the error itself, so one can tell real
233 problems with tests from expected errors. For example when testing
234 how the package behaves under error conditions the error_log file
235 might be loaded with errors, most of which are expected.
236 For example if a handler is about to generate a run-time error,
238 this function can be used as:
239 use Apache::TestUtil;
241 ...
242 sub handler {
243 my $r = shift;
244 ...
245 t_server_log_error_is_expected();
246 die "failed because ...";
247 }
248 After running this handler the error_log file will include:
250 *** The following error entry is expected and harmless ***
252 [Tue Apr 01 14:00:21 2003] [error] failed because ...
253 When more than one entry is expected, an optional numerical argu‐
255 ment, indicating how many entries to expect, can be passed. For
256 example:
257 t_server_log_error_is_expected(2);
259 will generate:
261 *** The following 2 error entries are expected and harmless ***
263 If the error is generated at compile time, the logging must be done
265 in the BEGIN block at the very beginning of the file:
266 BEGIN {
268 use Apache::TestUtil;
269 t_server_log_error_is_expected();
270 }
271 use DOES_NOT_exist;
272 After attempting to run this handler the error_log file will
274 include:
275 *** The following error entry is expected and harmless ***
277 [Tue Apr 01 14:04:49 2003] [error] Can't locate "DOES_NOT_exist.pm"
278 in @INC (@INC contains: ...
279 Also see "t_server_log_warn_is_expected()" which is similar but
281 used for warnings.
282 This function is exported by default.
284 t_server_log_warn_is_expected()
286 "t_server_log_warn_is_expected()" generates a disclaimer for
287 expected warnings.
288 See the explanation for "t_server_log_error_is_expected()" for more
290 details.
291 This function is exported by default.
293 t_client_log_error_is_expected()
295 "t_client_log_error_is_expected()" generates a disclaimer for
296 expected errors. But in contrast to
297 "t_server_log_error_is_expected()" called by the client side of the
298 script.
299 See the explanation for "t_server_log_error_is_expected()" for more
301 details.
302 For example the following client script fails to find the handler:
304 use Apache::Test;
306 use Apache::TestUtil;
307 use Apache::TestRequest qw(GET);
308 plan tests => 1;
310 t_client_log_error_is_expected();
312 my $url = "/error_document/cannot_be_found";
313 my $res = GET($url);
314 ok t_cmp(404, $res->code, "test 404");
315 After running this test the error_log file will include an entry
317 similar to the following snippet:
318 *** The following error entry is expected and harmless ***
320 [Tue Apr 01 14:02:55 2003] [error] [client 127.0.0.1]
321 File does not exist: /tmp/test/t/htdocs/error
322 When more than one entry is expected, an optional numerical argu‐
324 ment, indicating how many entries to expect, can be passed. For
325 example:
326 t_client_log_error_is_expected(2);
328 will generate:
330 *** The following 2 error entries are expected and harmless ***
332 This function is exported by default.
334 t_client_log_warn_is_expected()
336 "t_client_log_warn_is_expected()" generates a disclaimer for
337 expected warnings on the client side.
338 See the explanation for "t_client_log_error_is_expected()" for more
340 details.
341 This function is exported by default.
343 t_catfile('a', 'b', 'c')
345 This function is essentially "File::Spec->catfile", but on Win32
346 will use "Win32::GetLongpathName()" to convert the result to a long
347 path name (if the result is an absolute file). The function is not
348 exported by default.
349 t_catfile_apache('a', 'b', 'c')
351 This function is essentially "File::Spec::Unix->catfile", but on
352 Win32 will use "Win32::GetLongpathName()" to convert the result to
353 a long path name (if the result is an absolute file). It is useful
354 when comparing something to that returned by Apache, which uses a
355 Unix-style specification with forward slashes for directory separa‐
356 tors. The function is not exported by default.
357 t_start_error_log_watch(), t_finish_error_log_watch()
359 This pair of functions provides an easy interface for checking the
360 presence or absense of any particular message or messages in the
361 httpd error_log that were generated by the httpd daemon as part of
362 a test suite. It is likely, that you should proceed this with a
363 call to one of the t_*_is_expected() functions.
364 t_start_error_log_watch();
366 do_it;
367 ok grep {...} t_finish_error_log_watch()
368
370 Stas Bekman <stas@stason.org>
371
373 perl(1)
374perl v5.8.8 2006-11-19 Apache::TestUtil(3)