.\" Automatically generated by Pod::Man 4.10 (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 "Catalyst::Test 3pm"
.TH Catalyst::Test 3pm "2019-01-19" "perl v5.28.1" "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"
Catalyst::Test \- Test Catalyst Applications
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # Helper
\&    script/test.pl
\&
\&    # Tests
\&    use Catalyst::Test \*(AqTestApp\*(Aq;
\&    my $content  = get(\*(Aqindex.html\*(Aq);           # Content as string
\&    my $response = request(\*(Aqindex.html\*(Aq);       # HTTP::Response object
\&    my($res, $c) = ctx_request(\*(Aqindex.html\*(Aq);      # HTTP::Response & context object
\&
\&    use HTTP::Request::Common;
\&    my $response = request POST \*(Aq/foo\*(Aq, [
\&        bar => \*(Aqbaz\*(Aq,
\&        something => \*(Aqelse\*(Aq
\&    ];
\&
\&    # Run tests against a remote server
\&    CATALYST_SERVER=\*(Aqhttp://localhost:3000/\*(Aq prove \-r \-l lib/ t/
\&
\&    use Catalyst::Test \*(AqTestApp\*(Aq;
\&    use Test::More tests => 1;
\&
\&    ok( get(\*(Aq/foo\*(Aq) =~ /bar/ );
\&
\&    # mock virtual hosts
\&    use Catalyst::Test \*(AqMyApp\*(Aq, { default_host => \*(Aqmyapp.com\*(Aq };
\&    like( get(\*(Aq/whichhost\*(Aq), qr/served by myapp.com/ );
\&    like( get( \*(Aq/whichhost\*(Aq, { host => \*(Aqyourapp.com\*(Aq } ), qr/served by yourapp.com/ );
\&    {
\&        local $Catalyst::Test::default_host = \*(Aqotherapp.com\*(Aq;
\&        like( get(\*(Aq/whichhost\*(Aq), qr/served by otherapp.com/ );
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module allows you to make requests to a Catalyst application either without
a server, by simulating the environment of an \s-1HTTP\s0 request using
HTTP::Request::AsCGI or remotely if you define the \s-1CATALYST_SERVER\s0
environment variable. This module also adds a few Catalyst-specific
testing methods as displayed in the method section.
.PP
The get and request
functions take either a \s-1URI\s0 or an HTTP::Request object.
.SH "INLINE TESTS WILL NO LONGER WORK"
.IX Header "INLINE TESTS WILL NO LONGER WORK"
While it used to be possible to inline a whole test app into a \f(CW\*(C`.t\*(C'\fR file for
a distribution, this will no longer work.
.PP
The convention is to place your Catalyst test apps into \f(CW\*(C`t/lib\*(C'\fR in your
distribution. E.g.: \f(CW\*(C`t/lib/TestApp.pm\*(C'\fR, \f(CW\*(C`t/lib/TestApp/Controller/Root.pm\*(C'\fR,
etc..  Multiple test apps can be used in this way.
.PP
Then write your \f(CW\*(C`.t\*(C'\fR files like so:
.PP
.Vb 6
\&    use strict;
\&    use warnings;
\&    use FindBin \*(Aq$Bin\*(Aq;
\&    use lib "$Bin/lib";
\&    use Test::More tests => 6;
\&    use Catalyst::Test \*(AqTestApp\*(Aq;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$content = get( ... )"
.el .SS "\f(CW$content\fP = get( ... )"
.IX Subsection "$content = get( ... )"
Returns the content.
.PP
.Vb 1
\&    my $content = get(\*(Aqfoo/bar?test=1\*(Aq);
.Ve
.PP
Note that this method doesn't follow redirects, so to test for a
correctly redirecting page you'll need to use a combination of this
method and the request method below:
.PP
.Vb 6
\&    my $res = request(\*(Aq/\*(Aq); # redirects to /y
\&    warn $res\->header(\*(Aqlocation\*(Aq);
\&    use URI;
\&    my $uri = URI\->new($res\->header(\*(Aqlocation\*(Aq));
\&    is ( $uri\->path , \*(Aq/y\*(Aq);
\&    my $content = get($uri\->path);
.Ve
.PP
Note also that the content is returned as raw bytes, without any attempt
to decode it into characters.
.ie n .SS "$res = request( ... );"
.el .SS "\f(CW$res\fP = request( ... );"
.IX Subsection "$res = request( ... );"
Returns an HTTP::Response object. Accepts an optional hashref for request
header configuration; currently only supports setting 'host' value.
.PP
.Vb 2
\&    my $res = request(\*(Aqfoo/bar?test=1\*(Aq);
\&    my $virtual_res = request(\*(Aqfoo/bar?test=1\*(Aq, {host => \*(Aqvirtualhost.com\*(Aq});
.Ve
.PP
Alternately, you can pass in an HTTP::Request::Common object to set arbitrary
request headers.
.PP
.Vb 5
\&    my $res = request(GET \*(Aq/foo/bar\*(Aq,
\&        X\-Foo => \*(AqBar\*(Aq,
\&        Authorization => \*(AqBearer JWT_HERE\*(Aq,
\&        ...
\&    );
.Ve
.ie n .SS "($res, $c) = ctx_request( ... );"
.el .SS "($res, \f(CW$c\fP) = ctx_request( ... );"
.IX Subsection "($res, $c) = ctx_request( ... );"
Works exactly like request, except it also returns the Catalyst context object,
\&\f(CW$c\fR. Note that this only works for local requests.
.ie n .SS "action_ok($url [, $test_name ])"
.el .SS "action_ok($url [, \f(CW$test_name\fP ])"
.IX Subsection "action_ok($url [, $test_name ])"
Fetches the given \s-1URL\s0 and checks that the request was successful. An optional
second argument can be given to specify the name of the test.
.ie n .SS "action_redirect($url [, $test_name ])"
.el .SS "action_redirect($url [, \f(CW$test_name\fP ])"
.IX Subsection "action_redirect($url [, $test_name ])"
Fetches the given \s-1URL\s0 and checks that the request was a redirect. An optional
second argument can be given to specify the name of the test.
.ie n .SS "action_notfound($url [, $test_name ])"
.el .SS "action_notfound($url [, \f(CW$test_name\fP ])"
.IX Subsection "action_notfound($url [, $test_name ])"
Fetches the given \s-1URL\s0 and checks that the request was not found. An optional
second argument can be given to specify the name of the test.
.ie n .SS "content_like( $url, $regexp [, $test_name ] )"
.el .SS "content_like( \f(CW$url\fP, \f(CW$regexp\fP [, \f(CW$test_name\fP ] )"
.IX Subsection "content_like( $url, $regexp [, $test_name ] )"
Fetches the given \s-1URL\s0 and returns whether the content matches the regexp. An
optional third argument can be given to specify the name of the test.
.ie n .SS "contenttype_is($url, $type [, $test_name ])"
.el .SS "contenttype_is($url, \f(CW$type\fP [, \f(CW$test_name\fP ])"
.IX Subsection "contenttype_is($url, $type [, $test_name ])"
Verify the given \s-1URL\s0 has a content type of \f(CW$type\fR and optionally specify a test name.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catalyst, Test::WWW::Mechanize::Catalyst,
Test::WWW::Selenium::Catalyst, Test::More, HTTP::Request::Common
.SH "AUTHORS"
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.