NAME

Test::HTTP - Test HTTP interactions.

SYNOPSIS

 use Test::HTTP tests => 9;

 {
     my $uri = "$BASE/data/page/Foo_Bar_Baz";
     my $type = 'text/x.waki-wiki';
     my $test = Test::HTTP->new('HTTP page creation and deletion');

     $test->get($uri, [Accept => $type]);
     $test->status_code_is(404, "Page not yet there.");

     $test->put($uri, ['Content-type' => $type], 'xyzzy');
     $test->status_code_is(201, "PUT returns 201."); # Created
     $test->header_is(
         'Content-type' => $type,
         "Content-type matches on PUT.");
     $test->header_like(
         Location => qr{^$BASE/data/page/},
         "Created page location makes sense.");
     $test->body_is('xyzzy');

     $test->get($uri, [Accept => $type]);
     $test->status_code_is(200, "Page is now there.");
     $test->header_is(
         'Content-type' => $type,
         "Content-type matches on GET.");
     $test->body_is('xyzzy');

     $test->delete($uri);
     $test->status_code_is(204, "DELETE returns 204."); # No content
 }

DESCRIPTION

Test::HTTP is designed to make it easier to write tests which are mainly about HTTP-level things, such as REST-type services.

Each "Test::HTTP" object can contain state about a current request and its response. This allows convenient shorthands for sending requests, checking status codes, headers, and message bodies.

CONSTRUCTOR

Test::HTTP->new($name);

$name is a name for the test, used to help write test descriptions when you don't specify them.

OBJECT FIELDS

You can get/set any of these by saying "$test->foo" or "$test->foo(5)", respectively.

$test->request

The current HTTP::Request being constructed or most recently sent.

$test->response

The most recently received HTTP::Response.

$test->ua

The User Agent object (usually an LWP::UserAgent).

A username and password to be used for HTTP basic auth. Default to the values of $Test::HTTP::BasicUsername and $Test::HTTP::BasicPassword, respectively. If both are undef, then authentication is not attempted.

REQUEST METHODS

head, get, put, post, and delete

Any of these methods may be used to do perform the expected HTTP request. They are all equivalent to

  $obj->run_request(METHOD => ARGS);

$test->run_request([METHOD => $uri [, $headers [, $content]]]);

If there are any arguments, they are all passed to the HTTP::Request constructor to create a new "$test->request".

"$test->request" is then executed, and "$test->response" will hold the resulting HTTP::Response.

$test->new_request(METHOD => $uri [, $headers [, $content]]);

Set up a new request object as in run_request, but do not execute it yet. This is handy if you want to call assorted methods on the request to tweak it before running it with "$test->run_request".

TEST METHODS

$test->status_code_is($code [, $description]);

Compares the last response status code with the given code using "Test::Builder-"is>.

$test->header_is($header_name, $value [, $description]);

Compares the response header $header_name with the value $value using "Test::Builder-"is>.

$test->header_like($header_name, $regex, [, $description]);

Compares the response header $header_name with the regex $regex using "Test::Builder-"like>.

$test->body_is($expected_body [, $description]);

Verifies that the HTTP response body is exactly $expected_body.

$test->body_like($regex [, $description]);

Compares the HTTP response body with $regex.

USER AGENT GENERATION

The user agent (UA) is created when the "Test::HTTP" object is constructed. By default, LWP::UserAgent is used to create this object, but it may be handy to test your HTTP handlers without going through an actual HTTP server (for speed, e.g.), so there are a couple of ways to override the chosen class.

If the environment variable "TEST_HTTP_UA_CLASS" is set, this value is used instead. If not, then the current value of $Test::HTTP::UaClass ("LWP::UserAgent" by default) is used. Thus, the incantation below may prove useful.

    {
        local $Test::HTTP::UaClass = 'MyCorp::REST::FakeUserAgent';
        my $test = Test::HTTP->new("widget HTTP access");
        # ...
    }

AUTHOR

Socialtext, Inc. "<code@socialtext.com>"

COPYRIGHT & LICENSE

Same terms as Perl.