Index: lib/Apache/Test.pm =================================================================== RCS file: /home/cvspublic/httpd-test/perl-framework/Apache-Test/lib/Apache/Test.pm,v retrieving revision 1.62 diff -u -r1.62 Test.pm --- lib/Apache/Test.pm 29 May 2003 23:32:06 -0000 1.62 +++ lib/Apache/Test.pm 19 Jun 2003 16:08:20 -0000 @@ -656,6 +656,15 @@ # $tests will contain the Test.pm output: 1..4\nok 1\n... my $tests = Apache::TestToString->finish; +=head1 SEE ALSO + +L subclasses LWP::UserAgent and +exports a number of useful functions for sending request to the Apache test +server. You can then test the results of those requests. + +Use L in your F to set up your +distribution for testing. + =head1 AUTHOR Doug MacEachern with contributions from Geoffrey Young, Philippe Index: lib/Apache/TestRequest.pm =================================================================== RCS file: /home/cvspublic/httpd-test/perl-framework/Apache-Test/lib/Apache/TestRequest.pm,v retrieving revision 1.78 diff -u -r1.78 TestRequest.pm --- lib/Apache/TestRequest.pm 24 Apr 2003 05:16:57 -0000 1.78 +++ lib/Apache/TestRequest.pm 19 Jun 2003 16:08:22 -0000 @@ -88,6 +88,16 @@ $UA = undef; } + if (my $redir = $args->{requests_redirectable}) { + if (ref $redir and (@$redir > 1 or $redir->[0] ne 'POST')) { + $RedirectOK = 1; + } else { + $RedirectOK = 0; + } + } else { + $RedirectOK = $redir; + } + $args->{keep_alive} ||= $ENV{APACHE_TEST_HTTP11}; if ($args->{keep_alive}) { @@ -278,9 +288,6 @@ } push @$pass, content => $content; } - if (exists $keep->{redirect_ok}) { - $RedirectOK = $keep->{redirect_ok}; - } if ($keep->{cert}) { set_client_cert($keep->{cert}); } @@ -291,6 +298,9 @@ sub UPLOAD { my($url, $pass, $keep) = prepare(@_); + if (exists $keep->{redirect_ok}) { + local $RedirectOK = $keep->{redirect_ok}; + } if ($keep->{filename}) { return upload_file($url, $keep->{filename}, $pass); } @@ -451,6 +461,9 @@ *$name = sub { my($url, $pass, $keep) = prepare(@_); + if (exists $keep->{redirect_ok}) { + local $RedirectOK = $keep->{redirect_ok}; + } return lwp_call($method, undef, $url, @$pass); }; @@ -465,7 +478,7 @@ push @EXPORT, map { join '_', $method, $_ } keys %shortcuts; } -push @EXPORT, qw(UPLOAD_BODY UPLOAD_BODY_ASSERT); +push @EXPORT, qw(UPLOAD UPLOAD_BODY UPLOAD_BODY_ASSERT); sub to_string { my $obj = shift; @@ -606,3 +619,362 @@ } 1; + +=head1 NAME + +Apache::TestRequest - Send requests to your Apache test server + +=head1 SYNOPSIS + + use Apache::Test qw(ok have_lwp); + use Apache::TestRequest qw(GET POST); + use Apache::Constants qw(HTTP_OK); + + plan tests => 1, have_lwp; + + my $res = GET '/test.html'; + ok $res->code == HTTP_OK, "Request is ok"; + +=head1 DESCRIPTION + +B provides convenience functions to allow you to make +requests to your Apache test server in your test scripts. It subclasses +LWP::UserAgent, so that you have access to all if its methods, but also +exports a number of useful functions likely useful for majority of your test +requests. Users of the old Apache::test module, take note! Herein lie most of +the functions you'll need to use to replace Apache::test in your test suites. + +Each of the functions exported by Apache::TestRequest uses an LWP::UserAgent +object to submit the request and retrieve its results. The return value for +many of these functions is an HTTP::Response object. See +L for documentation of its methods, which you +can use in your tests. For example, use the C and C methods +to test the response code and content of your request. Using C, you can +perform a couple of tests using these methods like this: + + use Apache::Test qw(ok have_lwp); + use Apache::TestRequest qw(GET POST); + use Apache::Constants qw(HTTP_OK); + + plan tests => 2, have_lwp; + + my $uri = "/test.html?foo=1&bar=2"; + my $res = GET $uri; + ok $res->code == HTTP_OK, "Check that the request was OK"; + ok $res->content eq "foo => 1, bar => 2", "Check its content"; + +Note that you can also use Apache::TestRequest with Test::Builder and its +derivatives, including Test::More: + + use Test::More; + # ... + is $res->code, HTTP_OK, "Check that the request was OK"; + is $res->content, "foo => 1, bar => 2", "Check its content"; + +=head1 CONFIGURATION FUNCTION + +You can tell Apache::TestRequest what kind of LWP::UserAgent object to use for +its convenience functions with C. This function uses its +arguments to construct an internal global LWP::UserAgent object that will be +used for all subsequent requests made by the convenience functions. The +arguments it takes are the same as for the LWP::UserAgent constructor. See the +C documentation for a complete list. + +The C function only creates the internal LWP::UserAgent object +the first time it is called. Since this function is called internally by +Apache::TestRequest, you should always use the C parameter to force it +to create a new global LWP::UserAgent Object: + + Apache::TestRequest::user_agent(reset => 1, %params); + +C differs from C<< LWP::UserAgent->new >> in two additional +ways. First, it supports an additional parameter, C, which [XXX +What does it do, exactly?]. + +And finally, the semantics of the C parameter is +different than for LWP::UserAgent. Apache::TestRequest never follows redirects +for POST requests. However, it either follows redirects for all other kinds of +requests, or it doesn't. Thus C is a boolean value +instead of the array reference that LWP::UserAgent expects. Thus, to force +Apache::TestRequest not to follow redirects in any of its convenience +functions, pass a false value to C: + + Apache::TestRequest::user_agent(reset => 1, + requests_redirectable => 0); + +=head1 FUNCTIONS + +Apache::TestRequest exports a number of functions that will likely prove +convenient for use in the majority of your request tests. + +=head2 Optional Parameters + +Each function also takes a number of optional arguments. + +=over 4 + +=item redirect_ok + +By default they will follow redirects retrieved from the server. To prevent +this behavior, pass a false value to a C parameter: + + my $res = GET $uri, redirect_ok => 0; + +Alternately, if all of your tests need to disable redirects, tell +Apache::TestRequest to use an LWP::UserAgent object that disables redirects: + + Apache::TestRequest::user_agent( reset => 1, + requests_redirectable => 0 ); + +=item cert + +If you need to force an SSL request to use a particular SSL certificate, pass +the name of the certificate via the C parameter: + + my $res = GET $uri, cert = 'my_cert'; + +=item content + +If you need to add content to your request, use the C parameter: + + my $res = GET $uri, content = 'hello world!'; + +=item filename + +The name of a local file on the file system to be sent to the Apache test server +via and its friends. + +=back + +=head2 The Functions + +=over 4 + +=item GET + + my $res = GET $uri; + +Sends a simple GET request to the Apache test server. Returns an +HTTP::Response object. + +=item GET_STR + +A shortcut function for C<< GET($uri)->as_string >>. + +=item GET_BODY + +A shortcut function for C<< GET($uri)->content >>. + +=item GET_BODY_ASSERT + +Use this function when your test is outputting content that you need to check, +and you want to make sure that the request was successful before comparing +the contents of the request. If the request was unsuccessful, +C will return an error message. Otherwise it will simply +return the content of the request just as C would. + +=item GET_OK + +A shortcut function for C<< GET($uri)->is_success >>. + +=item GET_RC + +A shortcut function for C<< GET($uri)->code >>. + +=item GET_HEAD + +Throws out the content of the request, and returns the string representation +of the request. Since the body has been thrown out, the representation will +consist solely of the headers. Furthermore, C inserts a "#" at the +beginning of each line of the return string, so that the contents are suitable +for printing to STDERR during your tests without interfering with the workings +of Test::Harness. + +=item HEAD + + my $res = HEAD $uri; + +Sends a HEAD request to the Apache test server. Returns an HTTP::Response +object. + +=item HEAD_STR + +A shortcut function for C<< HEAD($uri)->as_string >>. + +=item HEAD_BODY + +A shortcut function for C<< HEAD($uri)->content >>. Of course, this means that +it will likely return nothing. + +=item HEAD_BODY_ASSERT + +Use this function when your test is outputting content that you need to check, +and you want to make sure that the request was successful before comparing +the contents of the request. If the request was unsuccessful, +C will return an error message. Otherwise it will simply +return the content of the request just as C would. + +=item HEAD_OK + +A shortcut function for C<< GET($uri)->is_success >>. + +=item HEAD_RC + +A shortcut function for C<< GET($uri)->code >>. + +=item HEAD_HEAD + +Throws out the content of the request, and returns the string representation +of the request. Since the body has been thrown out, the representation will +consist solely of the headers. Furthermore, C inserts a "#" at the +beginning of each line of the return string, so that the contents are suitable +for printing to STDERR during your tests without interfering with the workings +of Test::Harness. + +=item PUT + + my $res = PUT $uri; + +Sends a simple PUT request to the Apache test server. Returns an +HTTP::Response object. + +=item PUT_STR + +A shortcut function for C<< PUT($uri)->as_string >>. + +=item PUT_BODY + +A shortcut function for C<< PUT($uri)->content >>. + +=item PUT_BODY_ASSERT + +Use this function when your test is outputting content that you need to check, +and you want to make sure that the request was successful before comparing +the contents of the request. If the request was unsuccessful, +C will return an error message. Otherwise it will simply +return the content of the request just as C would. + +=item PUT_OK + +A shortcut function for C<< PUT($uri)->is_success >>. + +=item PUT_RC + +A shortcut function for C<< PUT($uri)->code >>. + +=item PUT_HEAD + +Throws out the content of the request, and returns the string representation +of the request. Since the body has been thrown out, the representation will +consist solely of the headers. Furthermore, C inserts a "#" at the +beginning of each line of the return string, so that the contents are suitable +for printing to STDERR during your tests without interfering with the workings +of Test::Harness. + +=item POST + + my $res = POST $uri, arg => $val, arg2 => $val; + +Sends a POST request to the Apache test server and returns an HTTP::Response +object. Any parameters passed after C<$uri> that do not correspond to those +documented in L will be submitted +to the Apache test server as the POST content. + +=item POST_STR + +A shortcut function for C<< POST($uri, @args)->content >>. + +=item POST_BODY + +A shortcut function for C<< POST($uri, @args)->content >>. + +=item POST_BODY_ASSERT + +Use this function when your test is outputting content that you need to check, +and you want to make sure that the request was successful before comparing +the contents of the request. If the request was unsuccessful, +C will return an error message. Otherwise it will simply +return the content of the request just as C would. + +=item POST_OK + +A shortcut function for C<< POST($uri, @args)->is_success >>. + +=item POST_RC + +A shortcut function for C<< POST($uri, @args)->code >>. + +=item POST_HEAD + +Throws out the content of the request, and returns the string representation +of the request. Since the body has been thrown out, the representation will +consist solely of the headers. Furthermore, C inserts a "#" at the +beginning of each line of the return string, so that the contents are suitable +for printing to STDERR during your tests without interfering with the workings +of Test::Harness. + +=item UPLOAD + + my $res = UPLOAD $uri, \@args, filename => $filename; + +Sends a request to the Apache test server that includes an uploaded +file. Other POST parameters can be passed as a second argument as an array +reference. + +Apache::TestRequest will read in the contents of the file named via the +C parameter for submission to the server. If you'd rather, you can +submit use the C parameter instead of C, and its value will +be submitted to the Apache server as file contents: + + my $res = UPLOAD $uri, undef, content => "This is file content"; + +The name of the file sent to the server will simply be "b". Note that in this +case, you cannot pass other POST arguments to C -- they would be +ignored. + +=item UPLOAD_BODY + +A shortcut function for C<< UPLOAD($uri, @params)->content >>. + +=item UPLOAD_BODY_ASSERT + +Use this function when your test is outputting content that you need to check, +and you want to make sure that the request was successful before comparing +the contents of the request. If the request was unsuccessful, +C will return an error message. Otherwise it will simply +return the content of the request just as C would. + +=item OPTIONS + +[I have no idea what these do.] + +=item OPTIONS_STR + +=item OPTIONS_BODY + +=item OPTIONS_BODY_ASSERT + +=item OPTIONS_OK + +=item OPTIONS_RC + +=item OPTIONS_HEAD + +=back + +=head1 SEE ALSO + +L is the main Apache testing module. Use it to set +up your tests, create a plan, and to ensure that you have the Apache version +and modules you need. + +Use L in your F to set up your +distribution for testing. + +=head1 AUTHOR + +Doug MacEachern with contributions from Geoffrey Young, Philippe M. Chiasson, +Stas Bekman and others. Documentation by David Wheeler. + +Questions can be asked at the test-dev httpd.apache.org list For more +information see: L.