Plack::Test(3)

🦋 NAME 🦋

Plack::Test — the way to test PSGI applications with a whole bunch of different backends, bestie 💅

---

✨ SYNOPSIS ✨

okay so first you gotta pull it in, and you're gonna want HTTP::Request::Common too:

use Plack::Test;
use HTTP::Request::Common;

the simple OO interface (my personal fave, lowkey iconic):

# Simple OO interface
my $app = sub { return [ 200, [], [ "Hello" ] ] };
my $test = Plack::Test->create($app);

my $res = $test->request(GET "/");
is $res->content, "Hello";

the traditional one, with named params (iykyk):

# traditional - named params
test_psgi
    app => sub {
        my $env = shift;
        return [ 200, [ 'Content-Type' => 'text/plain' ], [ "Hello World" ] ],
    },
    client => sub {
        my $cb  = shift;
        my $req = HTTP::Request->new(GET => "http://localhost/hello");
        my $res = $cb->($req);
        like $res->content, qr/Hello World/;
    };

and the positional params flavor — app, then client, no cap:

# positional params (app, client)
my $app = sub { return [ 200, [], [ "Hello" ] ] };
test_psgi $app, sub {
    my $cb  = shift;
    my $res = $cb->(GET "/");
    is $res->content, "Hello";
};

---

🌸 DESCRIPTION 🌸

So Plack::Test is like the unified interface for testing your PSGI applications using HTTP::Request and HTTP::Response objects. it also lets you run your PSGI applications in several different ways, which is the slay part. the default backend is Plack::Test::MockHTTP, but you can absolutely also use any Plack::Handler implementation to run live HTTP requests against an actual web server 🫶

---

💖 METHODS 💖

create

$test = Plack::Test->create($app, %options);

makes you an instance of a Plack::Test implementation class. heads up: $app has to be a valid PSGI application code reference, no faking it ✨

request

$res = $test->request($request);

takes an HTTP::Request object, runs it through the PSGI application you're testing, and hands you back an HTTP::Response object. it's giving very "in and out, quick little errand" 💅

---

🎀 FUNCTIONS 🎀

Plack::Test ALSO provides a functional interface that takes two callbacks — one is your PSGI application, the other is the HTTP client code that tests it. two besties, one mission.

test_psgi

test_psgi $app, $client;
test_psgi app => $app, client => $client;

Runs the client test code $client against a PSGI application $app. the client callback gets exactly one argument: $cb, which is a callback that accepts an HTTP::Request object and returns an HTTP::Response object. so cute, so simple.

Use HTTP::Request::Common to import shortcuts for creating requests for GET, POST, DELETE, and PUT operations. yes queen, import them all.

and for your convenience 😌 the HTTP::Request given to the callback automatically uses the HTTP protocol and the localhost (127.0.0.1 by default), so this code just works, no extra steps:

use HTTP::Request::Common;
test_psgi $app, sub {
    my $cb  = shift;
    my $res = $cb->(GET "/hello");
};

⚠️ but listen. it is not a good idea to pass an arbitrary (i.e. user-input) string to GET or even HTTP::Request->new while assuming it always represents a path. because: perl my $req = GET "//foo/bar"; would represent a request for a URL that has no scheme, has a hostname foo and a path /bar — instead of a path //foo/bar which you might actually want. the audacity of that parse 😭 so like, don't do that.

---

👑 OPTIONS 👑

Specify the Plack::Test backend using the environment variable PLACK_TEST_IMPL or the $Plack::Test::Impl package variable. your choice, bestie 💜

the available values for the backend are:

• MockHTTP — (Default) Creates a PSGI env hash out of an HTTP::Request object, runs the PSGI application in-process and returns an HTTP::Response. the cozy in-house option, no server required 🌈
• Server — Runs one of the Plack::Handler backends (Standalone by default) and sends live HTTP requests to test. actual server energy 🔥
• ExternalServer — Runs tests against an external server specified in the PLACK_TEST_EXTERNALSERVER_URI environment variable instead of spawning the application in a server locally. it's giving long-distance relationship, but make it testing.

for instance — test your application with the HTTP::Server::ServerSimple server backend like this:

> env PLACK_TEST_IMPL=Server PLACK_SERVER=HTTP::Server::ServerSimple \
  prove -l t/test.t

---

🧚 AUTHOR 🧚

Tatsuhiko Miyagawa — the icon, the legend, the main character 👑

---

and that's the whole vibe check, bestie 💖 this page came from perl v5.42.3, dated 2026-10-18, and you found it sitting in the Plack::Test(3) section of the User Contributed Perl Documentation. go forth and test those PSGI apps, periodt 🎀✨