.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "Dancer::Test 3pm"
.TH Dancer::Test 3pm "2020-01-30" "perl v5.30.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"
Dancer::Test \- Test helpers to test a Dancer application
.SH "VERSION"
.IX Header "VERSION"
version 1.3513
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use strict;
\&    use warnings;
\&    use Test::More tests => 2;
\&
\&    use MyWebApp;
\&    use Dancer::Test;
\&
\&    response_status_is [GET => \*(Aq/\*(Aq], 200, "GET / is found";
\&    response_content_like [GET => \*(Aq/\*(Aq], qr/hello, world/, "content looks good for /";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides test helpers for testing Dancer apps.
.PP
Be careful, the module loading order in the example above is very important.
Make sure to use \f(CW\*(C`Dancer::Test\*(C'\fR \fBafter\fR importing the application package
otherwise your appdir will be automatically set to \f(CW\*(C`lib\*(C'\fR and your test script
won't be able to find views, conffiles and other application content.
.PP
For all test methods, the first argument can be either an
array ref of the method and route, or a scalar containing the
route (in which case the method is assumed to be \f(CW\*(C`GET\*(C'\fR), or
a Dancer::Response object.
.PP
.Vb 2
\&    # all 3 are equivalent
\&    response_status_is [ GET => \*(Aq/\*(Aq ], 200, \*(AqGET / status is ok\*(Aq;
\&
\&    response_status_is \*(Aq/\*(Aq, 200, \*(AqGET / status is ok\*(Aq;
\&
\&    my $resp = dancer_response GET => \*(Aq/\*(Aq;
\&    response_status_is $resp => 200, \*(AqGET / status is ok\*(Aq;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.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 Dancer's
registry.
.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 Dancer's registry.
.PP
.Vb 1
\&    route_doesnt_exist [GET => \*(Aq/bogus_path\*(Aq], "GET /bogus_path is not handled";
.Ve
.ie n .SS "response_exists([$method, $path], $test_name)"
.el .SS "response_exists([$method, \f(CW$path\fP], \f(CW$test_name\fP)"
.IX Subsection "response_exists([$method, $path], $test_name)"
Deprecated \- Use response_status_isnt and check for status 404.
.PP
Asserts that a response is found for the given request (note that even though
a route for that path might not exist, a response can be found during request
processing, because of filters).
.PP
.Vb 2
\&    response_exists [GET => \*(Aq/path_that_gets_redirected_to_home\*(Aq],
\&        "response found for unknown path";
.Ve
.ie n .SS "response_doesnt_exist([$method, $path], $test_name)"
.el .SS "response_doesnt_exist([$method, \f(CW$path\fP], \f(CW$test_name\fP)"
.IX Subsection "response_doesnt_exist([$method, $path], $test_name)"
Deprecated \- Use response_status_is and check for status 404.
.PP
Asserts that no response is found when processing the given request.
.PP
.Vb 2
\&    response_doesnt_exist [GET => \*(Aq/unknown_path\*(Aq],
\&        "response not found for unknown path";
.Ve
.ie n .SS "response_status_is([$method, $path], $status, $test_name)"
.el .SS "response_status_is([$method, \f(CW$path\fP], \f(CW$status\fP, \f(CW$test_name\fP)"
.IX Subsection "response_status_is([$method, $path], $status, $test_name)"
Asserts that Dancer'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 "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 Dancer'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_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_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_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 => \*(AqDancer 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
.ie n .SS "response_redirect_location_is([$method, $path], $expected, $test_name)"
.el .SS "response_redirect_location_is([$method, \f(CW$path\fP], \f(CW$expected\fP, \f(CW$test_name\fP)"
.IX Subsection "response_redirect_location_is([$method, $path], $expected, $test_name)"
Asserts that the location header sent with a 302 redirect is equal to the \f(CW$expected\fR
location.
.PP
.Vb 1
\&    response_redirect_location_is [GET => \*(Aq/\*(Aq], \*(Aqhttp://localhost/index.html\*(Aq;
.Ve
.ie n .SS "response_redirect_location_like([$method, $path], $regexp, $test_name)"
.el .SS "response_redirect_location_like([$method, \f(CW$path\fP], \f(CW$regexp\fP, \f(CW$test_name\fP)"
.IX Subsection "response_redirect_location_like([$method, $path], $regexp, $test_name)"
Asserts that the location header sent with a 302 redirect matches the \f(CW$regexp\fR
provided. Useful if the redirect location includes a query string.
.PP
.Vb 1
\&    response_redirect_location_like [GET => \*(Aq/\*(Aq], qr/some_pattern/;
.Ve
.ie n .SS "dancer_response($method, $path, { params => $params, body => $body, headers => $headers, files => [{filename => '/path/to/file', name => 'my_file'}] })"
.el .SS "dancer_response($method, \f(CW$path\fP, { params => \f(CW$params\fP, body => \f(CW$body\fP, headers => \f(CW$headers\fP, files => [{filename => '/path/to/file', name => 'my_file'}] })"
.IX Subsection "dancer_response($method, $path, { params => $params, body => $body, headers => $headers, files => [{filename => '/path/to/file', name => 'my_file'}] })"
Returns a Dancer::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, \f(CW$body\fR can be a string or a hashref and \f(CW$headers\fR can be an arrayref or
a HTTP::Headers object, \f(CW$files\fR is an arrayref of hashref, containing some files to upload.
.PP
\&\f(CW$params\fR always populates the query string, even for \s-1POST\s0 requests.  \f(CW$body\fR
always populates the request body.
.PP
Currently, Dancer::Test cannot cope with both \fIbody\fR and \fIfiles\fR
passed in the same call.
.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
.SS "read_logs"
.IX Subsection "read_logs"
.Vb 1
\&    my $logs = read_logs;
.Ve
.PP
Returns an array ref of all log messages issued by the app since the
last call to \f(CW\*(C`read_logs\*(C'\fR.
.PP
For example:
.PP
.Vb 2
\&    warning "Danger!  Warning!";
\&    debug   "I like pie.";
\&
\&    is_deeply read_logs, [
\&        { level => "warning", message => "Danger!  Warning!" },
\&        { level => "debug",   message => "I like pie.", }
\&    ];
\&
\&    error "Put out the light.";
\&
\&    is_deeply read_logs, [
\&        { level => "error", message => "Put out the light." },
\&    ];
.Ve
.PP
See Dancer::Logger::Capture for more details.
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software and is distributed under the same terms as Perl
itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
This module has been written by Alexis Sukrieh <sukria@sukria.net>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test::More
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 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.