/ 
Test-HTTP-0.12
River stage zero No dependents
/ Test::HTTP

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->name

The name for the test.

$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).

$test->username

$test->password

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");
    # ...
}

SEE ALSO

http://www.w3.org/Protocols/rfc2616/rfc2616.html, LWP::UserAgent, HTTP::Request, HTTP::Response, Test::More, prove(1)

AUTHOR

Socialtext, Inc. <code@socialtext.com>

COPYRIGHT & LICENSE

Copyright 2006 Socialtext, Inc., all rights reserved.

SOME SUITABLE LICENSE TERMS GO HERE.