Dancer2::Test(3)

🎀 NAME 🎀

Dancer2::Test — useful routines for testing Dancer2 apps 💅 (it's a Perl module manual page, bestie, page 3 of the manual set, and we're about to have a conversation)

---

⭐ VERSION ⭐

version 2.2.1 ✨

---

🦋 SYNOPSIS 🦋

use Test::More;
use Plack::Test;
use HTTP::Request::Common; # install separately

use YourDancerApp;

my $app  = YourDancerApp->to_app;
my $test = Plack::Test->create($app);

my $res = $test->request( GET '/' );
is( $res->code, 200, '[GET /] Request successful' );
like( $res->content, qr/hello, world/, '[GET /] Correct content' );

done_testing;

---

💀 DESCRIPTION 💀

DEPRECATED. Okay so. Deep breath. This module, and literally every single function listed below it, is deprecated. Do not use this module. The routines it gives you for testing Dancer2 apps are buggy and unnecessary. Instead, use the Plack::Test module exactly like the SYNOPSIS up there shows, and just ignore all the functions in this documentation, iykyk. Go read the Plack::Test documentation for the real details. 👑

This module will be removed from the Dancer2 distribution in the near future. Not "someday maybe", like near future. You should migrate all your tests that use it over to the Plack::Test module and remove this module from your system. And because the module is not letting you forget it, it will throw warnings to remind you. 😭

For now (for now!!), you can silence the warnings by setting the NO_WARN option:

$Dancer::Test::NO_WARN = 1;

And in all the functions below, $test_name is always optional. 🫶

---

🌸 FUNCTIONS 🌸

💖 dancer_response ($method, $path, $params, $arg_env);

Returns a Dancer2::Core::Response object for the given request. Obsessed with how straightforward that sounds.

Only $method and $path are required. ✨

$params is a hashref with 'body' as a string; 'headers' can be an arrayref or a HTTP::Headers object, and 'files' can be an arrayref of hashref, containing some files to upload:

dancer_response($method, $path,
    {
        params => $params,
        body => $body,
        headers => $headers,
        files => [ { filename => '/path/to/file', name => 'my_file' } ],
    }
);

A good reason to use this function is for testing POST requests. Since POST requests may not be idempotent, it is necessary to capture the content and status in one shot. Calling the response_status_is and response_content_is functions in succession would make two requests, each of which could alter the state of the application and cause Schrodinger's cat to die. 😭🐈

my $response = dancer_response POST => '/widgets';
is $response->status, 202, "response for POST /widgets is 202";
is $response->content, "Widget #1 has been scheduled for creation",
    "response content looks good for first POST /widgets";

$response = dancer_response POST => '/widgets';
is $response->status, 202, "response for POST /widgets is 202";
is $response->content, "Widget #2 has been scheduled for creation",
    "response content looks good for second POST /widgets";

It's possible to test file uploads:

post '/upload' => sub { return upload('image')->content };

$response = dancer_response(POST => '/upload', {files => [{name => 'image', filename => '/path/to/image.jpg'}]});

In addition, you can supply the file contents as the "data" key:

my $data  = 'A test string that will pretend to be file contents.';
$response = dancer_response(POST => '/upload', {
    files => [{name => 'test', filename => "filename.ext", data => $data}]
});

You can also supply a hashref of headers:

headers => { 'Content-Type' => 'text/plain' }

---

💅 response_status_is ($request, $expected, $test_name);

Asserts that Dancer2's response for the given request has a status equal to the one given. Slay.

response_status_is [GET => '/'], 200, "response for GET / is 200";

---

🌈 route_exists([$method, $path], $test_name)

Asserts that the given request matches a route handler in Dancer2's registry. And here's the twist: if the route would have returned a 404, the route still exists and this test will pass. 💀

Note that because Dancer2 uses the default route handler Dancer2::Handler::File to match files in the public folder when no other route matches, this test will always pass. You can disable the default route handlers in the configs, but you probably want "response_status_is" in Dancer2::Test or "dancer_response" in Dancer2::Test.

route_exists [GET => '/'], "GET / is handled";

---

🙈 route_doesnt_exist([$method, $path], $test_name)

Asserts that the given request does not match any route handler in Dancer2's registry.

Note that this test is likely to always fail, as any route not matched will be handled by the default route handler in Dancer2::Handler::File. This can be disabled in the configs. 😭

route_doesnt_exist [GET => '/bogus_path'], "GET /bogus_path is not handled";

---

🍓 response_status_isnt([$method, $path], $status, $test_name)

Asserts that the status of Dancer2's response is not equal to the one given.

response_status_isnt [GET => '/'], 404, "response for GET / is not a 404";

---

🧚 response_content_is([$method, $path], $expected, $test_name)

Asserts that the response content is equal to the $expected string.

 response_content_is [GET => '/'], "Hello, World",
        "got expected response content for GET /";

---

💜 response_content_isnt([$method, $path], $not_expected, $test_name)

Asserts that the response content is not equal to the $not_expected string.

response_content_isnt [GET => '/'], "Hello, World",
    "got expected response content for GET /";

---

👑 response_content_like([$method, $path], $regexp, $test_name)

Asserts that the response content for the given request matches the regexp given.

response_content_like [GET => '/'], qr/Hello, World/,
    "response content looks good for GET /";

---

🌸 response_content_unlike([$method, $path], $regexp, $test_name)

Asserts that the response content for the given request does not match the regexp given.

response_content_unlike [GET => '/'], qr/Page not found/,
    "response content looks good for GET /";

---

✨ response_content_is_deeply([$method, $path], $expected_struct, $test_name)

Similar to response_content_is(), except that if response content and $expected_struct are references, it does a deep comparison, walking each data structure to see if they are equivalent. It's giving thorough. 💅

If the two structures are different, it will display the place where they start differing.

response_content_is_deeply [GET => '/complex_struct'],
    { foo => 42, bar => 24},
    "got expected response structure for GET /complex_struct";

---

🫶 response_is_file ($request, $test_name);

---

🌈 response_headers_are_deeply([$method, $path], $expected, $test_name)

Asserts that the response headers data structure equals the one given.

response_headers_are_deeply [GET => '/'], [ 'X-Powered-By' => 'Dancer2 1.150' ];

---

🎀 response_headers_include([$method, $path], $expected, $test_name)

Asserts that the response headers data structure includes some of the defined ones.

response_headers_include [GET => '/'], [ 'Content-Type' => 'text/plain' ];

---

🦋 route_pod_coverage()

Returns a structure describing pod coverage in your apps 📚

For one app like this:

package t::lib::TestPod;
use Dancer2;

=head1 NAME

TestPod

=head2 ROUTES

=over

=cut

=item get "/in_testpod"

testpod

=cut

get '/in_testpod' => sub {
    return 'get in_testpod';
};

get '/hello' => sub {
    return "hello world";
};

=item post '/in_testpod/*'

post in_testpod

=cut

post '/in_testpod/*' => sub {
    return 'post in_testpod';
};

=back

=head2 SPECIALS

=head3 PUBLIC

=over

=item get "/me:id"

=cut

get "/me:id" => sub {
    return "ME";
};

=back

=head3 PRIVAT

=over

=item post "/me:id"

post /me:id

=cut

post "/me:id" => sub {
    return "ME";
};

=back

=cut

1;

route_pod_coverage;

would return something like:

{
    't::lib::TestPod' => {
        'has_pod'             => 1,
        'routes'              => [
            "post /in_testpod/*",
            "post /me:id",
            "get /in_testpod",
            "get /hello",
            "get /me:id"
        ],
        'undocumented_routes' => [
            "get /hello"
        ]
    }
}

---

⭐ is_pod_covered('is pod covered')

Asserts that your apps have pods for all routes 🌟

is_pod_covered 'is pod covered'

To avoid test failures, you should document all your routes with one of the following: head1, head2, head3, head4, item.

Example:

=item get '/login'

route to login

=cut

If you use:

any '/myaction' => sub {
    # code
}

or

any ['get', 'post'] => '/myaction' => sub {
    # code
};

then you need to create pods for each one of the routes created there. No skipping, bestie. 💅

---

🔥 import

When Dancer2::Test is imported, it should be passed all the applications that are supposed to be tested.

If none passed, then the caller is supposed to be the sole application to test.

# t/sometest.t

use t::lib::Foo;
use t::lib::Bar;

use Dancer2::Test apps => ['t::lib::Foo', 't::lib::Bar'];

---

🌟 AUTHOR 🌟

Dancer Core Developers 👑

---

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2026 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

---

Okay that's the whole page bestie, tysm for reading 💖 this was generated by perl v5.42.3 on 2026-09-20 and it's the Dancer2::Test(3) manual page — go use Plack::Test instead, mwah 💅✨