view release on metacpan or  search on metacpan

lib/Catalyst/Manual/Cookbook.pod  view on Meta::CPAN

development and before deployment in a real environment.

L<Catalyst::Test> makes it possible to run the same tests both locally
(without an external daemon) and against a remote server via HTTP.

=head3 Tests

Let's examine a skeleton application's F<t/> directory:

    mundus:~/MyApp chansen$ ls -l t/
    total 24
    -rw-r--r--  1 chansen  chansen   95 18 Dec 20:50 01app.t
    -rw-r--r--  1 chansen  chansen  190 18 Dec 20:50 02pod.t
    -rw-r--r--  1 chansen  chansen  213 18 Dec 20:50 03podcoverage.t

=over 4

=item F<01app.t>

Verifies that the application loads, compiles, and returns a successful
response.

=item F<02pod.t>

Verifies that all POD is free from errors. Only executed if the C<TEST_POD>
environment variable is true.

=item F<03podcoverage.t>

Verifies that all methods/functions have POD coverage. Only executed if the
C<TEST_POD> environment variable is true.

=back

=head3 Creating tests

    mundus:~/MyApp chansen$ cat t/01app.t | perl -ne 'printf( "%2d  %s", $., $_ )'
    1  use Test::More tests => 2;
    2  BEGIN { use_ok( Catalyst::Test, 'MyApp' ) }
    3
    4  ok( request('/')->is_success );

The first line declares how many tests we are going to run, in this case
two. The second line tests and loads our application in test mode. The
fourth line verifies that our application returns a successful response.

L<Catalyst::Test> exports two functions, C<request> and C<get>. Each can
take three different arguments:

=over 4

=item A string which is a relative or absolute URI.

    request('/my/path');
    request('http://www.host.com/my/path');

=item An instance of L<URI>.

    request( URI->new('http://www.host.com/my/path') );

=item An instance of L<HTTP::Request>.

    request( HTTP::Request->new( GET => 'http://www.host.com/my/path') );

=back

C<request> returns an instance of L<HTTP::Response> and C<get> returns the
content (body) of the response.

=head3 Running tests locally

    mundus:~/MyApp chansen$ CATALYST_DEBUG=0 TEST_POD=1 prove --lib lib/ t/
    t/01app............ok
    t/02pod............ok
    t/03podcoverage....ok
    All tests successful.
    Files=3, Tests=4,  2 wallclock secs ( 1.60 cusr +  0.36 csys =  1.96 CPU)

C<CATALYST_DEBUG=0> ensures that debugging is off; if it's enabled you
will see debug logs between tests.

C<TEST_POD=1> enables POD checking and coverage.

C<prove> A command-line tool that makes it easy to run tests. You can
find out more about it from the links below.

=head3 Running tests remotely

    mundus:~/MyApp chansen$ CATALYST_SERVER=http://localhost:3000/ prove --lib lib/ t/01app.t
    t/01app....ok
    All tests successful.
    Files=1, Tests=2,  0 wallclock secs ( 0.40 cusr +  0.01 csys =  0.41 CPU)

C<CATALYST_SERVER=http://localhost:3000/> is the absolute deployment URI of
your application. In C<CGI> or C<FastCGI> it should be the host and path
to the script.

=head3 L<Test::WWW::Mechanize> and Catalyst

Be sure to check out L<Test::WWW::Mechanize::Catalyst>. It makes it easy to
test HTML, forms and links. A short example of usage:

    use Test::More tests => 6;
    BEGIN { use_ok( Test::WWW::Mechanize::Catalyst, 'MyApp' ) }

    my $mech = Test::WWW::Mechanize::Catalyst->new;
    $mech->get_ok("http://localhost/", 'Got index page');
    $mech->title_like( qr/^MyApp on Catalyst/, 'Got right index title' );
    ok( $mech->find_link( text_regex => qr/^Wiki/i ), 'Found link to Wiki' );
    ok( $mech->find_link( text_regex => qr/^Mailing-List/i ), 'Found link to Mailing-List' );
    ok( $mech->find_link( text_regex => qr/^IRC channel/i ), 'Found link to IRC channel' );

=head3 Further Reading

=over 4

=item * L<Catalyst::Test>

=item * L<Test::WWW::Mechanize::Catalyst>

=item * L<Test::WWW::Mechanize>

=item * L<WWW::Mechanize>

=item * L<LWP::UserAgent>

=item * L<HTML::Form>

=item * L<HTTP::Message>

=item * L<HTTP::Request>

=item * L<HTTP::Request::Common>

=item * L<HTTP::Response>

=item * L<HTTP::Status>

=item * L<URI>

=item * L<Test::More>

=item * L<Test::Pod>

=item * L<Test::Pod::Coverage>

=item * L<prove> (L<Test::Harness>)

=back

=head3 More Information

=over 4

=item * L<Catalyst::Plugin::Authorization::Roles>

=item * L<Catalyst::Plugin::Authorization::ACL>

=back

=head1 AUTHORS

Catalyst Contributors, see Catalyst.pm

=head1 COPYRIGHT

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

=cut