.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Dancer2::Test 3pm"
.TH Dancer2::Test 3pm "2023-12-15" "perl v5.36.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"
Dancer2::Test \- Useful routines for testing Dancer2 apps
.SH "VERSION"
.IX Header "VERSION"
version 1.1.0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    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 \*(Aq/\*(Aq );
\&    is( $res\->code, 200, \*(Aq[GET /] Request successful\*(Aq );
\&    like( $res\->content, qr/hello, world/, \*(Aq[GET /] Correct content\*(Aq );
\&
\&    done_testing;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1DEPRECATED.\s0 This module and all the functions listed below are deprecated. Do
not use this module.\fR The routines provided by this module for testing Dancer2
apps are buggy and unnecessary. Instead, use the Plack::Test module as shown
in the \s-1SYNOPSIS\s0 above and ignore the functions in this documentation. Consult
the Plack::Test documentation for further details.
.PP
This module will be removed from the Dancer2 distribution in the near future.
You should migrate all tests that use it over to the Plack::Test module and
remove this module from your system. This module will throw warnings to remind
you.
.PP
For now, you can silence the warnings by setting the \f(CW\*(C`NO_WARN\*(C'\fR option:
.PP
.Vb 1
\&    $Dancer::Test::NO_WARN = 1;
.Ve
.PP
In the functions below, \f(CW$test_name\fR is always optional.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "dancer_response ($method, $path, $params, $arg_env);"
.el .SS "dancer_response ($method, \f(CW$path\fP, \f(CW$params\fP, \f(CW$arg_env\fP);"
.IX Subsection "dancer_response ($method, $path, $params, $arg_env);"
Returns a Dancer2::Core::Response object for the given request.
.PP
Only \f(CW$method\fR and \f(CW$path\fR are required.
.PP
\&\f(CW$params\fR is a hashref with 'body' as a string; 'headers' can be an arrayref or
a HTTP::Headers object, 'files' can be arrayref of hashref, containing some
files to upload:
.PP
.Vb 8
\&    dancer_response($method, $path,
\&        {
\&            params => $params,
\&            body => $body,
\&            headers => $headers,
\&            files => [ { filename => \*(Aq/path/to/file\*(Aq, name => \*(Aqmy_file\*(Aq } ],
\&        }
\&    );
.Ve
.PP
A good reason to use this function is for testing \s-1POST\s0 requests. Since \s-1POST\s0
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.
.PP
.Vb 4
\&    my $response = dancer_response POST => \*(Aq/widgets\*(Aq;
\&    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 => \*(Aq/widgets\*(Aq;
\&    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";
.Ve
.PP
It's possible to test file uploads:
.PP
.Vb 1
\&    post \*(Aq/upload\*(Aq => sub { return upload(\*(Aqimage\*(Aq)\->content };
\&
\&    $response = dancer_response(POST => \*(Aq/upload\*(Aq, {files => [{name => \*(Aqimage\*(Aq, filename => \*(Aq/path/to/image.jpg\*(Aq}]});
.Ve
.PP
In addition, you can supply the file contents as the \f(CW\*(C`data\*(C'\fR key:
.PP
.Vb 4
\&    my $data  = \*(AqA test string that will pretend to be file contents.\*(Aq;
\&    $response = dancer_response(POST => \*(Aq/upload\*(Aq, {
\&        files => [{name => \*(Aqtest\*(Aq, filename => "filename.ext", data => $data}]
\&    });
.Ve
.PP
You can also supply a hashref of headers:
.PP
.Vb 1
\&    headers => { \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq }
.Ve
.ie n .SS "response_status_is ($request, $expected, $test_name);"
.el .SS "response_status_is ($request, \f(CW$expected\fP, \f(CW$test_name\fP);"
.IX Subsection "response_status_is ($request, $expected, $test_name);"
Asserts that Dancer2's response for the given request has a status equal to the
one given.
.PP
.Vb 1
\&    response_status_is [GET => \*(Aq/\*(Aq], 200, "response for GET / is 200";
.Ve
.ie n .SS "route_exists([$method, $path], $test_name)"
.el .SS "route_exists([$method, \f(CW$path\fP], \f(CW$test_name\fP)"
.IX Subsection "route_exists([$method, $path], $test_name)"
Asserts that the given request matches a route handler in Dancer2's
registry. If the route would have returned a 404, the route still exists
and this test will pass.
.PP
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 \*(L"response_status_is\*(R" in Dancer2::Test or \*(L"dancer_response\*(R" in Dancer2::Test
.PP
.Vb 1
\&    route_exists [GET => \*(Aq/\*(Aq], "GET / is handled";
.Ve
.ie n .SS "route_doesnt_exist([$method, $path], $test_name)"
.el .SS "route_doesnt_exist([$method, \f(CW$path\fP], \f(CW$test_name\fP)"
.IX Subsection "route_doesnt_exist([$method, $path], $test_name)"
Asserts that the given request does not match any route handler
in Dancer2's registry.
.PP
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.
.PP
.Vb 1
\&    route_doesnt_exist [GET => \*(Aq/bogus_path\*(Aq], "GET /bogus_path is not handled";
.Ve
.ie n .SS "response_status_isnt([$method, $path], $status, $test_name)"
.el .SS "response_status_isnt([$method, \f(CW$path\fP], \f(CW$status\fP, \f(CW$test_name\fP)"
.IX Subsection "response_status_isnt([$method, $path], $status, $test_name)"
Asserts that the status of Dancer2's response is not equal to the
one given.
.PP
.Vb 1
\&    response_status_isnt [GET => \*(Aq/\*(Aq], 404, "response for GET / is not a 404";
.Ve
.ie n .SS "response_content_is([$method, $path], $expected, $test_name)"
.el .SS "response_content_is([$method, \f(CW$path\fP], \f(CW$expected\fP, \f(CW$test_name\fP)"
.IX Subsection "response_content_is([$method, $path], $expected, $test_name)"
Asserts that the response content is equal to the \f(CW$expected\fR string.
.PP
.Vb 2
\& response_content_is [GET => \*(Aq/\*(Aq], "Hello, World",
\&        "got expected response content for GET /";
.Ve
.ie n .SS "response_content_isnt([$method, $path], $not_expected, $test_name)"
.el .SS "response_content_isnt([$method, \f(CW$path\fP], \f(CW$not_expected\fP, \f(CW$test_name\fP)"
.IX Subsection "response_content_isnt([$method, $path], $not_expected, $test_name)"
Asserts that the response content is not equal to the \f(CW$not_expected\fR string.
.PP
.Vb 2
\&    response_content_isnt [GET => \*(Aq/\*(Aq], "Hello, World",
\&        "got expected response content for GET /";
.Ve
.ie n .SS "response_content_like([$method, $path], $regexp, $test_name)"
.el .SS "response_content_like([$method, \f(CW$path\fP], \f(CW$regexp\fP, \f(CW$test_name\fP)"
.IX Subsection "response_content_like([$method, $path], $regexp, $test_name)"
Asserts that the response content for the given request matches the regexp
given.
.PP
.Vb 2
\&    response_content_like [GET => \*(Aq/\*(Aq], qr/Hello, World/,
\&        "response content looks good for GET /";
.Ve
.ie n .SS "response_content_unlike([$method, $path], $regexp, $test_name)"
.el .SS "response_content_unlike([$method, \f(CW$path\fP], \f(CW$regexp\fP, \f(CW$test_name\fP)"
.IX Subsection "response_content_unlike([$method, $path], $regexp, $test_name)"
Asserts that the response content for the given request does not match the regexp
given.
.PP
.Vb 2
\&    response_content_unlike [GET => \*(Aq/\*(Aq], qr/Page not found/,
\&        "response content looks good for GET /";
.Ve
.ie n .SS "response_content_is_deeply([$method, $path], $expected_struct, $test_name)"
.el .SS "response_content_is_deeply([$method, \f(CW$path\fP], \f(CW$expected_struct\fP, \f(CW$test_name\fP)"
.IX Subsection "response_content_is_deeply([$method, $path], $expected_struct, $test_name)"
Similar to \fBresponse_content_is()\fR, except that if response content and
\&\f(CW$expected_struct\fR are references, it does a deep comparison walking each data
structure to see if they are equivalent.
.PP
If the two structures are different, it will display the place where they start
differing.
.PP
.Vb 3
\&    response_content_is_deeply [GET => \*(Aq/complex_struct\*(Aq],
\&        { foo => 42, bar => 24},
\&        "got expected response structure for GET /complex_struct";
.Ve
.ie n .SS "response_is_file ($request, $test_name);"
.el .SS "response_is_file ($request, \f(CW$test_name\fP);"
.IX Subsection "response_is_file ($request, $test_name);"
.ie n .SS "response_headers_are_deeply([$method, $path], $expected, $test_name)"
.el .SS "response_headers_are_deeply([$method, \f(CW$path\fP], \f(CW$expected\fP, \f(CW$test_name\fP)"
.IX Subsection "response_headers_are_deeply([$method, $path], $expected, $test_name)"
Asserts that the response headers data structure equals the one given.
.PP
.Vb 1
\&    response_headers_are_deeply [GET => \*(Aq/\*(Aq], [ \*(AqX\-Powered\-By\*(Aq => \*(AqDancer2 1.150\*(Aq ];
.Ve
.ie n .SS "response_headers_include([$method, $path], $expected, $test_name)"
.el .SS "response_headers_include([$method, \f(CW$path\fP], \f(CW$expected\fP, \f(CW$test_name\fP)"
.IX Subsection "response_headers_include([$method, $path], $expected, $test_name)"
Asserts that the response headers data structure includes some of the defined ones.
.PP
.Vb 1
\&    response_headers_include [GET => \*(Aq/\*(Aq], [ \*(AqContent\-Type\*(Aq => \*(Aqtext/plain\*(Aq ];
.Ve
.SS "\fBroute_pod_coverage()\fP"
.IX Subsection "route_pod_coverage()"
Returns a structure describing pod coverage in your apps
.PP
for one app like this:
.PP
.Vb 2
\&    package t::lib::TestPod;
\&    use Dancer2;
\&
\&    =head1 NAME
\&
\&    TestPod
\&
\&    =head2 ROUTES
\&
\&    =over
\&
\&    =cut
\&
\&    =item get "/in_testpod"
\&
\&    testpod
\&
\&    =cut
\&
\&    get \*(Aq/in_testpod\*(Aq => sub {
\&        return \*(Aqget in_testpod\*(Aq;
\&    };
\&
\&    get \*(Aq/hello\*(Aq => sub {
\&        return "hello world";
\&    };
\&
\&    =item post \*(Aq/in_testpod/*\*(Aq
\&
\&    post in_testpod
\&
\&    =cut
\&
\&    post \*(Aq/in_testpod/*\*(Aq => sub {
\&        return \*(Aqpost in_testpod\*(Aq;
\&    };
\&
\&    =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;
.Ve
.PP
route_pod_coverage;
.PP
would return something like:
.PP
.Vb 10
\&    {
\&        \*(Aqt::lib::TestPod\*(Aq => {
\&            \*(Aqhas_pod\*(Aq             => 1,
\&            \*(Aqroutes\*(Aq              => [
\&                "post /in_testpod/*",
\&                "post /me:id",
\&                "get /in_testpod",
\&                "get /hello",
\&                "get /me:id"
\&            ],
\&            \*(Aqundocumented_routes\*(Aq => [
\&                "get /hello"
\&            ]
\&        }
\&    }
.Ve
.SS "is_pod_covered('is pod covered')"
.IX Subsection "is_pod_covered('is pod covered')"
Asserts that your apps have pods for all routes
.PP
.Vb 1
\&    is_pod_covered \*(Aqis pod covered\*(Aq
.Ve
.PP
to avoid test failures, you should document all your routes with one of the following:
head1, head2,head3,head4, item.
.PP
.Vb 1
\&    ex:
\&
\&    =item get \*(Aq/login\*(Aq
\&
\&    route to login
\&
\&    =cut
\&
\&    if you use:
\&
\&    any \*(Aq/myaction\*(Aq => sub {
\&        # code
\&    }
\&
\&    or
\&
\&    any [\*(Aqget\*(Aq, \*(Aqpost\*(Aq] => \*(Aq/myaction\*(Aq => sub {
\&        # code
\&    };
\&
\&    you need to create pods for each one of the routes created there.
.Ve
.SS "import"
.IX Subsection "import"
When Dancer2::Test is imported, it should be passed all the
applications that are supposed to be tested.
.PP
If none passed, then the caller is supposed to be the sole application
to test.
.PP
.Vb 1
\&    # t/sometest.t
\&
\&    use t::lib::Foo;
\&    use t::lib::Bar;
\&
\&    use Dancer2::Test apps => [\*(Aqt::lib::Foo\*(Aq, \*(Aqt::lib::Bar\*(Aq];
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2023 by Alexis Sukrieh.
.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.