# NAME

Plack::Test::Simple - Object-Oriented PSGI Application Testing

# VERSION

version 0.02

# STATUS

<a href="https://travis-ci.org/alnewkirk/Plack-Test-Simple"><img src="https://travis-ci.org/alnewkirk/Plack-Test-Simple.svg?branch=master"></a>

# SYNOPSIS

    use Test::More;
    use Plack::Test::Simple;

    # prepare test container
    my $t = Plack::Test::Simple->new('/path/to/app.psgi');

    # global request configuration
    my $req = $t->request;
    $req->headers->authorization_basic('h@cker', 's3cret');
    $req->headers->content_type('application/json');

    # standard GET request test
    # automatic JSON serialization if content-body is a hash/array reference
    my $tx = $t->transaction('get', '/search?q=awesomeness', 'content body');
    $tx->data_has('/results/4/title', 'test description');

    done_testing;

# DESCRIPTION

Plack::Test::Simple is a collection of testing helpers for anyone developing
Plack applications. This module is a wrapper around [Plack::Test](http://search.cpan.org/perldoc?Plack::Test) providing a
unified interface to test PSGI applications using [HTTP::Request](http://search.cpan.org/perldoc?HTTP::Request) and
[HTTP::Response](http://search.cpan.org/perldoc?HTTP::Response) objects. Typically a Plack web application's deployment stack
includes various middlewares and utilities which are now even easier to test
along-side the actual web application code.

# ATTRIBUTES

## request

The request attribute contains the [HTTP::Request](http://search.cpan.org/perldoc?HTTP::Request) object which will be used
to process the HTTP requests. This attribute is never reset.

## psgi

The psgi attribute contains a coderef containing the PSGI compliant application
code. If this value is a string containing the path to the psgi file, the
application code will be coerced.

# METHODS

## transaction

The transaction method returns a [Plack::Test::Simple::Transaction](http://search.cpan.org/perldoc?Plack::Test::Simple::Transaction) object
containing the HTTP request and response object that will be used to facilitate
the HTTP transaction. The actually HTTP request is deferred until the response
object is needed, this allows you to further modify the transactions HTTP
request object before it is processed. This method optionally accepts an HTTP
request method, a request path (or URI object), and content (any string) you
wish to place in the body of the request. If the content body argument is a
hash/array reference, we will attempt to encode and serialize it automatically
as a JSON object. These parameters are used to further modify the transaction's
request object. Please see [Plack::Test::Simple::Transaction](http://search.cpan.org/perldoc?Plack::Test::Simple::Transaction) for more
information on how to use the transaction object to further automate tests.

    my $tx = $self->transaction('post', '/path/to/resource', 'content body');

## connect\_returns\_CODE

The connect\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->connect_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->connect_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('connect', '/path/to/resource');
    $tx->status_is(200, 'test description');

## delete\_returns\_CODE

The delete\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->delete_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->delete_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('delete', '/path/to/resource');
    $tx->status_is(200, 'test description');

## get\_returns\_CODE

The get\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->get_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->get_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('get', '/path/to/resource');
    $tx->status_is(200, 'test description');

## head\_returns\_CODE

The head\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->head_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->head_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('head', '/path/to/resource');
    $tx->status_is(200, 'test description');

## options\_returns\_CODE

The options\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->options_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->options_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('options', '/path/to/resource');
    $tx->status_is(200, 'test description');

## patch\_returns\_CODE

The patch\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->patch_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->patch_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('patch', '/path/to/resource');
    $tx->status_is(200, 'test description');

## post\_returns\_CODE

The post\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->post_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->post_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('post', '/path/to/resource');
    $tx->status_is(200, 'test description');

## put\_returns\_CODE

The put\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->put_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->put_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('put', '/path/to/resource');
    $tx->status_is(200, 'test description');

## trace\_returns\_CODE

The trace\_returns\_CODE method is a shorthand method for returning a
transaction object much like the transaction method except the the actual HTTP
request is made and the server's HTTP response code is tested to ensure it
returns a CODE. The CODE in this method description is a variable which
represents any valid HTTP response code, e.g. 200.

    my $tx = $self->trace_returns_200(
        '/path/to/resource', 'content body'
    );

    # with content body and status test description included
    my $tx = $self->trace_returns_200(
        '/path/to/resource', 'content body', 'test description'
    );

    # shorthand for
    my $tx = $self->transaction('trace', '/path/to/resource');
    $tx->status_is(200, 'test description');

# AUTHOR

Al Newkirk <anewkirk@ana.io>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Al Newkirk.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
