.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Plack::Test::Agent 3pm" .TH Plack::Test::Agent 3pm "2022-10-14" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Plack::Test::Agent \- OO interface for testing low\-level Plack/PSGI apps .SH "VERSION" .IX Header "VERSION" version 1.5 .SS "\s-1SYNOPSIS\s0" .IX Subsection "SYNOPSIS" .Vb 2 \& 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 => \*(AqHTTP::Server::Simple\*(Aq ); \& \& my $local_res = $local_agent\->get( \*(Aq/\*(Aq ); \& my $server_res = $server_agent\->get( \*(Aq/\*(Aq ); \& \& ok $local_res\->is_success, \*(Aqlocal GET / should succeed\*(Aq; \& ok $server_res\->is_success, \*(Aqserver GET / should succeed\*(Aq; .Ve .SS "\s-1DESCRIPTION\s0" .IX Subsection "DESCRIPTION" \&\f(CW\*(C`Plack::Test::Agent\*(C'\fR is an \s-1OO\s0 interface to test \s-1PSGI\s0 applications. It can perform \s-1GET\s0 and \s-1POST\s0 requests against \s-1PSGI\s0 applications either in process or over \s-1HTTP\s0 through a Plack::Handler compatible backend. .PP \&\fB\s-1NOTE:\s0\fR This is an experimental module and its interface may change. .SS "\s-1CONSTRUCTION\s0" .IX Subsection "CONSTRUCTION" \fI\f(CI\*(C`new\*(C'\fI\fR .IX Subsection "new" .PP The \f(CW\*(C`new\*(C'\fR constructor creates an instance of \f(CW\*(C`Plack::Test::Agent\*(C'\fR. This constructor takes one mandatory named argument and several optional arguments. .IP "\(bu" 4 \&\f(CW\*(C`app\*(C'\fR is the mandatory argument. You must provide a \s-1PSGI\s0 application to test. .IP "\(bu" 4 \&\f(CW\*(C`server\*(C'\fR is an optional argument. When provided, \f(CW\*(C`Plack::Test::Agent\*(C'\fR will attempt to start a \s-1PSGI\s0 handler and will communicate via \s-1HTTP\s0 to the application running through the handler. See Plack::Loader for details on selecting the appropriate server. .IP "\(bu" 4 \&\f(CW\*(C`host\*(C'\fR is an optional argument representing the name or \s-1IP\s0 address for the server to use. The default is \f(CW\*(C`localhost\*(C'\fR. .IP "\(bu" 4 \&\f(CW\*(C`port\*(C'\fR is an optional argument representing the \s-1TCP\s0 port to for the server to use. If not provided, the service will run on a randomly selected available port outside of the \s-1IANA\s0 reserved range. (See Test::TCP for details on the selection of the port number.) .IP "\(bu" 4 \&\f(CW\*(C`ua\*(C'\fR is an optional argument of something which conforms to the LWP::UserAgent interface such that it provides a \f(CW\*(C`request\*(C'\fR method which takes an HTTP::Request object and returns an HTTP::Response object. The default is an instance of \f(CW\*(C`LWP::UserAgent\*(C'\fR. .IP "\(bu" 4 \&\f(CW\*(C`jar\*(C'\fR is an optional argument for a HTTP::Cookies instance that will be used as cookie jar for the requests, by default plain one is created. .SS "\s-1METHODS\s0" .IX Subsection "METHODS" This class provides several useful methods: .PP \fI\f(CI\*(C`get\*(C'\fI\fR .IX Subsection "get" .PP This method takes a \s-1URI\s0 and makes a \f(CW\*(C`GET\*(C'\fR request against the \s-1PSGI\s0 application with that \s-1URI.\s0 It returns an HTTP::Response object representing the results of that request. .PP \fI\f(CI\*(C`post\*(C'\fI\fR .IX Subsection "post" .PP This method takes a \s-1URI\s0 and makes a \f(CW\*(C`POST\*(C'\fR request against the \s-1PSGI\s0 application with that \s-1URI.\s0 It returns an 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: .PP .Vb 6 \& $agent\->post( \*(Aq/edit_user\*(Aq, \& [ \& shoe_size => \*(Aq10.5\*(Aq, \& eye_color => \*(Aqblue green\*(Aq, \& status => \*(Aqtwin\*(Aq, \& ]); .Ve .PP \fI\f(CI\*(C`execute_request\*(C'\fI\fR .IX Subsection "execute_request" .PP This method takes an HTTP::Request, performs it against the bound app, and returns an HTTP::Response. This allows you to craft your own requests directly. .PP \fI\f(CI\*(C`get_mech\*(C'\fI\fR .IX Subsection "get_mech" .PP Used internally to create a default UserAgent, if none is provided to the constructor. Returns a Test::WWW::Mechanize::Bound object. .PP \fI\f(CI\*(C`normalize_uri\*(C'\fI\fR .IX Subsection "normalize_uri" .PP Used internally to ensure that all requests use the correct scheme, host and port. The scheme and host default to \f(CW\*(C`http\*(C'\fR and \f(CW\*(C`localhost\*(C'\fR respectively, while the port is determined by Test::TCP. .PP \fI\f(CI\*(C`start_server\*(C'\fI\fR .IX Subsection "start_server" .PP Starts a test server via Test::TCP. If a \f(CW\*(C`server\*(C'\fR 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. .SS "\s-1CREDITS\s0" .IX Subsection "CREDITS" Thanks to Zbigniew Łukasiak and Tatsuhiko Miyagawa for suggestions. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 chromatic .IP "\(bu" 4 Dave Rolsky .IP "\(bu" 4 Ran Eilam .IP "\(bu" 4 Olaf Alders .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Dave Rolsky .IP "\(bu" 4 Olaf Alders .IP "\(bu" 4 Ran Eilam .IP "\(bu" 4 Syohei \s-1YOSHIDA\s0 .IP "\(bu" 4 Torsten Raudssus .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2011 by chromatic. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.