view release on metacpan or  search on metacpan

lib/Apache/TestUtil.pm  view on Meta::CPAN

  t_start_error_log_watch();
  do_it;
  ok grep {...} t_finish_error_log_watch();

Another usage case could be a handler that emits some debugging messages
to the error_log. Now, if this handler is called in a series of other
test cases it can be hard to find the relevant messages manually. In such
cases the following sequence in the test file may help:

  t_start_error_log_watch();
  GET '/this/or/that';
  t_debug t_finish_error_log_watch();

=item t_start_file_watch()

  Apache::TestUtil::t_start_file_watch('access_log');

This function is similar to C<t_start_error_log_watch()> but allows for
other files than C<error_log> to be watched. It opens the given file
and positions the file pointer at its end. Subsequent calls to
C<t_read_file_watch()> or C<t_finish_file_watch()> will read lines that
have been appended after this call.

A file name can be passed as parameter. If omitted
or undefined the C<error_log> is opened. Relative file name are
evaluated relative to the directory containing C<error_log>.

If the specified file does not exist (yet) no error is returned. It is
assumed that it will appear soon. In this case C<t_{read,finish}_file_watch()>
will open the file silently and read from the beginning.

=item t_read_file_watch(), t_finish_file_watch()

  local $/ = "\n";
  $line1=Apache::TestUtil::t_read_file_watch('access_log');
  $line2=Apache::TestUtil::t_read_file_watch('access_log');

  @lines=Apache::TestUtil::t_finish_file_watch('access_log');

This pair of functions reads the file opened by C<t_start_error_log_watch()>.

As does the core C<readline> function, they return one line if called in
scalar context, otherwise all lines until end of file.

Before calling C<readline> these functions do not set C<$/> as does
C<t_finish_error_log_watch>. So, if the file has for example a fixed
record length use this:

  {
    local $/=\$record_length;
    @lines=t_finish_file_watch($name);
  }

=item t_file_watch_for()

  @lines=Apache::TestUtil::t_file_watch_for('access_log',
                                            qr/condition/,
                                            $timeout);

This function reads the file from the current position and looks for the
first line that matches C<qr/condition/>. If no such line could be found
until end of file the function pauses and retries until either such a line
is found or the timeout (in seconds) is reached.

In scalar or void context only the matching line is returned. In list
context all read lines are returned with the matching one in last position.

The function uses C<\n> and end-of-line marker and waits for complete lines.

The timeout although it can be specified with sub-second precision is not very
accurate. It is simply multiplied by 10. The result is used as a maximum loop
count. For the intented purpose this should be good enough.

Use this function to check for logfile entries when you cannot be sure that
they are already written when the test program reaches the point, for example
to check for messages that are written in a PerlCleanupHandler or a
PerlLogHandler.

 ok t_file_watch_for 'access_log', qr/expected log entry/, 2;

This call reads the C<access_log> and waits for maximum 2 seconds for the
expected entry to appear.

=back

=head1 AUTHOR

Stas Bekman <stas@stason.org>,
Torsten Förtsch <torsten.foertsch@gmx.net>

=head1 SEE ALSO

perl(1)

=cut