Plack:...:Agent(3pm)

💖 Plack::Test::Agent — the manual, but make it cute

okay bestie, welcome to the Plack:...:Agent(3pm) page, aka the docs for Plack::Test::Agent ✨ it's the OO interface for testing low-level Plack/PSGI apps, and yes you're literally about to be obsessed 💅

✨ NAME ✨

Plack::Test::Agent — an OO interface for testing low-level Plack/PSGI apps 🧚

✨ VERSION ✨

version 1.6 🎀

✨ SYNOPSIS ✨

no cap, this is the whole vibe:

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';

like, you got a local one and a server one, and both of them are serving 💅

---

✨ DESCRIPTION ✨

Plack::Test::Agent is an OO interface to test PSGI applications 🦋 she can perform GET, POST, PUT and DELETE requests against your PSGI apps — either in process (nice and cozy, no network drama) or over HTTP through a Plack::Handler compatible backend 🌸

it's giving "I test everything, I fear nothing" 👑

---

✨ CONSTRUCTION ✨

new 🌈

The new constructor creates an instance of Plack::Test::Agent. She takes one mandatory named argument and several optional ones, and honestly? iconic. Here's the whole lineup:

• app — this one's the mandatory argument, no exceptions bestie 😤 you must provide a PSGI application to test.
• server — optional! when you provide it, Plack::Test::Agent will attempt to start a PSGI handler and will communicate via HTTP to the application running through that handler 🌐 for the deets on picking the right server, go peep Plack::Loader.
• host — optional, it's the name or IP address for the server to use. default is localhost 🏠
• port — optional, the TCP port for the server to use. if you don't provide one, the service will run on a randomly selected available port outside of the IANA reserved range 🎲 (see Test::TCP for how that port number gets picked, iykyk).
• ua — optional, and it has to be something that conforms to the LWP::UserAgent interface, meaning it provides a request method that takes an HTTP::Request object and returns an HTTP::Response object 💌 the default is an instance of LWP::UserAgent.
• jar — optional, an HTTP::Cookies instance to be used as the cookie jar for requests 🍪 by default a plain one gets created for you. cookies stay warm, periodt.

---

✨ METHODS ✨

This class provides several useful methods and honestly each one ate 🔥

get 🫶

This method takes a URI and makes a GET request against the PSGI application with that URI. It returns an 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 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',
    ]);

look at those form values, very main character 🦋

put ✨

This method takes a URI and makes a PUT request against the PSGI application with that URI. 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:

$agent->put( '/edit_user',
    [
        shoe_size => '10.5',
        eye_color => 'blue green',
        status    => 'twin',
    ]);

same energy, different HTTP verb, slay 💅

delete 🗑️

This method takes a URI and makes a DELETE request against the PSGI application with that URI. It returns an HTTP::Response object representing the results of that request. (no build-a-form moment here, just vibes.)

execute_request ⚡

This method takes an HTTP::Request, performs it against the bound app, and returns an HTTP::Response 🎯 this is the one where you get to craft your own requests directly, like a lil artisan. obsessed.

get_mech 🕹️

Used internally to create a default UserAgent, if none is provided to the constructor. Returns a Test::WWW::Mechanize::Bound object. She's the backup plan and she showed up ready 💖

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. everything gets tidied, no chaos allowed ✨

start_server 🚀

Starts a test server via 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. let the loader choose, she knows what's up 👑

---

✨ CREDITS ✨

Thanks to Zbigniew Łukasiak and Tatsuhiko Miyagawa for suggestions 🫶 absolute legends for that.

✨ AUTHORS ✨

• chromatic <chromatic@wgz.org>
• Dave Rolsky <autarch@urth.org>
• Ran Eilam <ran.eilam@gmail.com>
• Olaf Alders <olaf@wundercounter.com>

✨ CONTRIBUTORS ✨

• Andy Beverley <andy@andybev.com>
• Dave Rolsky <drolsky@maxmind.com>
• Olaf Alders <oalders@maxmind.com>
• Ran Eilam <reilam@maxmind.com>
• Syohei YOSHIDA <syohex@gmail.com>
• Torsten Raudssus <torsten@raudss.us>

✨ COPYRIGHT AND LICENSE ✨

This software is copyright (c) 2011 by chromatic. 📜

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself 🌸 (yes bestie, free as in do-what-you-want-within-those-terms, we love a permissive queen.)

---

ok that's the whole page, no skips, no cuts 💖 everything's in there exactly as written, we just gave it the glow-up it deserved ✨

and for the cute sign-off: this lil rendering came from perl v5.40.1, dated 2025-10-07, and it's the Plack:...:Agent(3pm) manual page — User Contributed Perl Documentation energy all the way 🎀 byeeee 💅🌈