# NAME Plack::Test::Agent - OO interface for testing low-level Plack/PSGI apps # VERSION version 1.3 ## SYNOPSIS use Test::More; use Plack::Test::Agent; my $app = sub { ... }; my $local_agent = Plack::Test::Agent->new( app => $app ); my $server_agent = Plack::Test::Agent->new( app => $app, server => 'HTTP::Server::Simple' ); my $local_res = $local_agent->get( '/' ); my $server_res = $server_agent->get( '/' ); ok $local_res->is_success, 'local GET / should succeed'; ok $server_res->is_success, 'server GET / should succeed'; ## DESCRIPTION `Plack::Test::Agent` is an OO interface to test PSGI applications. It can perform GET and POST requests against PSGI applications either in process or over HTTP through a [Plack::Handler](https://metacpan.org/pod/Plack::Handler) compatible backend. **NOTE:** This is an experimental module and its interface may change. ## CONSTRUCTION ### `new` The `new` constructor creates an instance of `Plack::Test::Agent`. This constructor takes one mandatory named argument and several optional arguments. - `app` is the mandatory argument. You must provide a PSGI application to test. - `server` is an optional argument. When provided, `Plack::Test::Agent` will attempt to start a PSGI handler and will communicate via HTTP to the application running through the handler. See [Plack::Loader](https://metacpan.org/pod/Plack::Loader) for details on selecting the appropriate server. - `host` is an optional argument representing the name or IP address for the server to use. The default is `localhost`. - `port` is an optional argument representing the TCP port to for the server to use. If not provided, the service will run on a randomly selected available port outside of the IANA reserved range. (See [Test::TCP](https://metacpan.org/pod/Test::TCP) for details on the selection of the port number.) - `ua` is an optional argument of something which conforms to the [LWP::UserAgent](https://metacpan.org/pod/LWP::UserAgent) interface such that it provides a `request` method which takes an [HTTP::Request](https://metacpan.org/pod/HTTP::Request) object and returns an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object. The default is an instance of `LWP::UserAgent`. ## METHODS This class provides several useful methods: ### `get` This method takes a URI and makes a `GET` request against the PSGI application with that URI. It returns an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object representing the results of that request. ### `post` This method takes a URI and makes a `POST` request against the PSGI application with that URI. It returns an [HTTP::Response](https://metacpan.org/pod/HTTP::Response) object representing the results of that request. As an optional second parameter, pass an array reference of key/value pairs for the form content: $agent->post( '/edit_user', [ shoe_size => '10.5', eye_color => 'blue green', status => 'twin', ]); ### `execute_request` This method takes an [HTTP::Request](https://metacpan.org/pod/HTTP::Request), performs it against the bound app, and returns an [HTTP::Response](https://metacpan.org/pod/HTTP::Response). This allows you to craft your own requests directly. ### `get_mech` Used internally to create a default UserAgent, if none is provided to the constructor. Returns a Test::WWW::Mechanize::Bound object. ### `normalize_uri` Used internally to ensure that all requests use the correct scheme, host and port. The scheme and host default to `http` and `localhost` respectively, while the port is determined by [Test::TCP](https://metacpan.org/pod/Test::TCP). ### `start_server` Starts a test server via [Test::TCP](https://metacpan.org/pod/Test::TCP). If a `server` arg has been provided to the constructor, it will use this class to load a server. Defaults to letting Plack::Loader decide which server class to use. ## CREDITS Thanks to Zbigniew Łukasiak and Tatsuhiko Miyagawa for suggestions. # AUTHORS - chromatic - Dave Rolsky - Ran Eilam - Olaf Alders # CONTRIBUTORS - Dave Rolsky - Olaf Alders - Ran Eilam # COPYRIGHT AND LICENSE This software is copyright (c) 2011 - 2015 by MaxMind, Inc.. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.