view release on metacpan or  search on metacpan

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

        } else {
            return $_[0];
        }
    }
}

my $banner_format =
    "\n*** The following %s expected and harmless ***\n";

sub is_expected_banner {
    my $type  = shift;
    my $count = @_ ? shift : 1;
    sprintf $banner_format, $count == 1
        ? "$type entry is"
        : "$count $type entries are";
}

sub t_server_log_is_expected {
    print STDERR is_expected_banner(@_);
}

sub t_client_log_is_expected {
    my $vars = Apache::Test::config()->{vars};
    my $log_file = catfile $vars->{serverroot}, "logs", "error_log";

    my $fh = Symbol::gensym();
    open $fh, ">>$log_file" or die "Can't open $log_file: $!";
    my $oldfh = select($fh); $| = 1; select($oldfh);
    print $fh is_expected_banner(@_);
    close $fh;
}

sub t_server_log_error_is_expected { t_server_log_is_expected("error", @_);}
sub t_server_log_warn_is_expected  { t_server_log_is_expected("warn", @_); }
sub t_client_log_error_is_expected { t_client_log_is_expected("error", @_);}
sub t_client_log_warn_is_expected  { t_client_log_is_expected("warn", @_); }

END {
    # remove files that were created via this package
    for (grep {-e $_ && -f _ } keys %{ $CLEAN{files} } ) {
        t_debug("removing file: $_");
        unlink $_;
    }

    # remove dirs that were created via this package
    for (grep {-e $_ && -d _ } keys %{ $CLEAN{dirs} } ) {
        t_debug("removing dir tree: $_");
        t_rmtree($_);
    }
}

# essentially File::Spec->catfile, but on Win32
# returns the long path name, if the file is absolute
sub t_catfile {
    my $f = catfile(@_);
    return $f unless file_name_is_absolute($f);
    return Apache::TestConfig::WIN32 && -e $f ?
        Win32::GetLongPathName($f) : $f;
}

# Apache uses a Unix-style specification for files, with
# forward slashes for directory separators. This is
# essentially File::Spec::Unix->catfile, but on Win32
# returns the long path name, if the file is absolute
sub t_catfile_apache {
    my $f = File::Spec::Unix->catfile(@_);
    return $f unless file_name_is_absolute($f);
    return Apache::TestConfig::WIN32 && -e $f ?
        Win32::GetLongPathName($f) : $f;
}

1;
__END__

=encoding utf8

=head1 NAME

Apache::TestUtil - Utility functions for writing tests

=head1 SYNOPSIS

  use Apache::Test;
  use Apache::TestUtil;

  ok t_cmp("foo", "foo", "sanity check");
  t_write_file("filename", @content);
  my $fh = t_open_file($filename);
  t_mkdir("/foo/bar");
  t_rmtree("/foo/bar");
  t_is_equal($a, $b);

=head1 DESCRIPTION

C<Apache::TestUtil> automatically exports a number of functions useful
in writing tests.

All the files and directories created using the functions from this
package will be automatically destroyed at the end of the program
execution (via END block). You should not use these functions other
than from within tests which should cleanup all the created
directories and files at the end of the test.

=head1 FUNCTIONS

=over

=item t_cmp()

  t_cmp($received, $expected, $comment);

t_cmp() prints the values of I<$comment>, I<$expected> and
I<$received>. e.g.:

  t_cmp(1, 1, "1 == 1?");

prints:

  # testing : 1 == 1?
  # expected: 1
  # received: 1

then it returns the result of comparison of the I<$expected> and the
I<$received> variables. Usually, the return value of this function is
fed directly to the ok() function, like this:

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

=item t_client_log_error_is_expected()

C<t_client_log_error_is_expected()> generates a disclaimer for
expected errors. But in contrast to
C<t_server_log_error_is_expected()> called by the client side of the
script.

See the explanation for C<t_server_log_error_is_expected()> for more
details.

For example the following client script fails to find the handler:

  use Apache::Test;
  use Apache::TestUtil;
  use Apache::TestRequest qw(GET);

  plan tests => 1;

  t_client_log_error_is_expected();
  my $url = "/error_document/cannot_be_found";
  my $res = GET($url);
  ok t_cmp(404, $res->code, "test 404");

After running this test the I<error_log> file will include an entry
similar to the following snippet:

  *** The following error entry is expected and harmless ***
  [Tue Apr 01 14:02:55 2003] [error] [client 127.0.0.1]
  File does not exist: /tmp/test/t/htdocs/error

When more than one entry is expected, an optional numerical argument,
indicating how many entries to expect, can be passed. For example:

  t_client_log_error_is_expected(2);

will generate:

  *** The following 2 error entries are expected and harmless ***

This function is exported by default.

=item t_client_log_warn_is_expected()

C<t_client_log_warn_is_expected()> generates a disclaimer for expected
warnings on the client side.

See the explanation for C<t_client_log_error_is_expected()> for more
details.

This function is exported by default.

=item t_catfile('a', 'b', 'c')

This function is essentially C<File::Spec-E<gt>catfile>, but
on Win32 will use C<Win32::GetLongpathName()> to convert the
result to a long path name (if the result is an absolute file).
The function is not exported by default.

=item t_catfile_apache('a', 'b', 'c')

This function is essentially C<File::Spec::Unix-E<gt>catfile>, but
on Win32 will use C<Win32::GetLongpathName()> to convert the
result to a long path name (if the result is an absolute file).
It is useful when comparing something to that returned by Apache,
which uses a Unix-style specification with forward slashes for
directory separators. The function is not exported by default.

=item t_start_error_log_watch(), t_finish_error_log_watch()

This pair of functions provides an easy interface for checking
the presence or absense of any particular message or messages
in the httpd error_log that were generated by the httpd daemon
as part of a test suite.  It is likely, that you should proceed
this with a call to one of the t_*_is_expected() functions.

  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;