Catalyst::Test(3pm)

💖 Catalyst::Test — the manual, but make it make sense 💖

okay so bestie, you found it: Catalyst::Test(3pm), the module that lets you test Catalyst apps without ever spinning up a server. It's giving ✨dev-velocity✨, it's giving 🦋no more manual clicking🦋. Let's get into it.

---

🌸 NAME 🌸

Catalyst::Test — Test Catalyst Applications. That's it, that's the whole vibe. 🎀

---

✨ SYNOPSIS ✨

Here's the tea, straight up ☕ — helper script first, then the tests:

# Helper
script/test.pl

# Tests
use Catalyst::Test 'TestApp';
my $content  = get('index.html');           # Content as string
my $response = request('index.html');       # HTTP::Response object
my($res, $c) = ctx_request('index.html');      # HTTP::Response & context object

use HTTP::Request::Common;
my $response = request POST '/foo', [
    bar => 'baz',
    something => 'else'
];

# Run tests against a remote server
CATALYST_SERVER='http://localhost:3000/' prove -r -l lib/ t/

use Catalyst::Test 'TestApp';
use Test::More tests => 1;

ok( get('/foo') =~ /bar/ );

# mock virtual hosts
use Catalyst::Test 'MyApp', { default_host => 'myapp.com' };
like( get('/whichhost'), qr/served by myapp.com/ );
like( get( '/whichhost', { host => 'yourapp.com' } ), qr/served by yourapp.com/ );
{
    local $Catalyst::Test::default_host = 'otherapp.com';
    like( get('/whichhost'), qr/served by otherapp.com/ );
}

no cap, that last block with the local is the main character energy move for temporarily switching your default host. 👑

---

🦋 DESCRIPTION 🦋

So here's what this module actually does, bestie: it lets you fire off requests at a Catalyst application two ways:

1. No server at all — it simulates the environment of an HTTP request using HTTP::Request::AsCGI.
2. Remotely — if you define the CATALYST_SERVER environment variable, it'll go talk to a real server instead.

On top of that, it sprinkles in a few Catalyst-specific testing methods, all listed down in the method section below. 🫶

Oh and important: the get and request functions will take either a URI or an HTTP::Request object. Flexible queen. 💅

---

💀 INLINE TESTS WILL NO LONGER WORK 💀

Not me being the bearer of bad news but yeah — this one's a real glow-down. It used to be possible to inline a whole test app into a .t file for a distribution, and this will no longer work. Periodt. 🚫

The convention now is to place your Catalyst test apps into t/lib inside your distribution. Like so: t/lib/TestApp.pm, t/lib/TestApp/Controller/Root.pm, etc. And yes, you can absolutely have multiple test apps living in there at the same time. 🌈

Then you write your .t files like this:

use strict;
use warnings;
use FindBin '$Bin';
use lib "$Bin/lib";
use Test::More tests => 6;
use Catalyst::Test 'TestApp';

---

🎀 METHODS 🎀

$content = get( ... )

Returns the content. That's the whole job. 💖

my $content = get('foo/bar?test=1');

⚠️ Okay listen up, because this is the part people mess up: this method doesn't follow redirects. So if you want to test a page that redirects correctly, you gotta combo it with the request method below. Teamwork makes the dream work. 🤝

my $res = request('/'); # redirects to /y
warn $res->header('location');
use URI;
my $uri = URI->new($res->header('location'));
is ( $uri->path , '/y');
my $content = get($uri->path);

Also also also — the content comes back as raw bytes, with zero attempt to decode it into characters. No decoding, no vibes, just bytes. 🫠

$res = request( ... );

Returns an HTTP::Response object. 🎁 It takes an optional hashref for request header configuration, but heads up — right now it only supports setting the 'host' value.

my $res = request('foo/bar?test=1');
my $virtual_res = request('foo/bar?test=1', {host => 'virtualhost.com'});

Or, alternately, you can pass in an HTTP::Request::Common object to set arbitrary request headers. That's your full-control era:

my $res = request(GET '/foo/bar',
    X-Foo => 'Bar',
    Authorization => 'Bearer JWT_HERE',
    ...
);

($res, $c) = ctx_request( ... );

Works exactly like request, except it also hands you the Catalyst context object, $c. Two for the price of one, iconic. 👑

⚠️ But note: this only works for local requests. Remote? No context for you, bestie. 🙈

action_ok($url [, $test_name ])

Fetches the given URL and checks that the request was successful. You can optionally pass a second argument to name the test. ✨

action_redirect($url [, $test_name ])

Fetches the given URL and checks that the request was a redirect. Optional second argument = test name. 🌀

action_notfound($url [, $test_name ])

Fetches the given URL and checks that the request was not found. Optional second argument = test name. 💀

content_like( $url, $regexp [, $test_name ] )

Fetches the given URL and returns whether the content matches the regexp. Optional third argument = test name. 🔍

contenttype_is($url, $type [, $test_name ])

Verify the given URL has a content type of $type, and optionally specify a test name. ✅

---

🫶 SEE ALSO 🫶

Go read these next, iykyk:

• Catalyst
• Test::WWW::Mechanize::Catalyst
• Test::WWW::Selenium::Catalyst
• Test::More
• HTTP::Request::Common

---

👑 AUTHORS 👑

Catalyst Contributors, see Catalyst.pm. A whole squad, we love to see it. 🌟

---

💜 COPYRIGHT 💜

This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. Free is free, bestie. 🍓

---

okay and that's the whole page, we ate fr fr — this was Catalyst::Test(3pm), documented under perl v5.40.0 on 2024-11-15, and that's the sign-off. go write some tests and slay 💅✨🦋