lib/Catalyst/Manual/Tutorial/Testing.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Testing - Catalyst Tutorial - Part 7: Testing
   4
   5
   6
   7 =head1 OVERVIEW
   8
   9 This is B<Part 7 of 9> for the Catalyst tutorial.
  10
  11 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  12
  13 =over 4
  14
  15 =item 1
  16
  17 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  18
  19 =item 2
  20
  21 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  22
  23 =item 3
  24
  25 L<Basic CRUD|Catalyst::Manual::Tutorial_BasicCRUD>
  26
  27 =item 4
  28
  29 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  30
  31 =item 5
  32
  33 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  34
  35 =item 6
  36
  37 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  38
  39 =item 7
  40
  41 B<Testing>
  42
  43 =item 8
  44
  45 L<AdvancedCRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  46
  47 =item 9
  48
  49 L<Appendicies|Catalyst::Manual::Tutorial::Appendicies>
  50
  51 =back
  52
  53
  54
  55 =head1 DESCRIPTION
  56
  57
  58 You may have noticed that the Catalyst Helper scripts automatically
  59 create C<.t> test scripts under the C<t> directory.  This part of the
  60 tutorial briefly looks at how these tests can be used to not only ensure
  61 that your application is working correctly at the present time, but also
  62 provide automated regression testing as you upgrade various pieces of
  63 your application over time.
  64
  65 B<TIP>: Note that all of the code for this part of the tutorial can be
  66 pulled from the Catalyst Subversion repository in one step with the
  67 following command:
  68
  69     svn checkout http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial@###
  70     IMPORTANT: Does not work yet.  Will be completed for final version.
  71
  72
  73
  74 =head1 RUNNING THE "CANNED" CATALYST TESTS
  75
  76 There are a variety of ways to run Catalyst and Perl tests (for example,
  77 C<perl Makefile.PL> and C<make test>, but one of the easiest is with the
  78 C<prove> command.  For example, to run all of the tests in the C<t>
  79 directory, enter:
  80
  81     $ prove --lib lib t
  82
  83 The redirection used by the Authentication plugins will cause the
  84 default C<t/01app.t> to fail.  You can fix this by changing the line in
  85 C<t/01app.t> that read:
  86
  87     ok( request('/')->is_success, 'Request should succeed' );
  88
  89 to:
  90
  91     ok( request('/login')->is_success, 'Request should succeed' );
  92
  93 So that a redirect is not necessary.  Also, the C<t/controller_Books.t>
  94 and C<t/controller_Logout.t> default test cases will fail because of the
  95 authorization.  You can delete these two files to prevent false error
  96 messages:
  97
  98     $ rm t/controller_Books.t
  99     $ rm t/controller_Logout.t
 100
 101 As you can see in the C<prove> command line above, the C<--lib> option
 102 is used to set the location of the Catalyst C<lib> directory.  With this
 103 command, you will get all of the usual development server debug output,
 104 something most people prefer to disable while running tests cases.
 105 Although you can edit the C<lib/MyApp.pm> to comment out the C<-Debug>
 106 plugin, it's generally easier to simply set the C<CATALYST_DEBUG=0>
 107 environment variable.  For example:
 108
 109     CATALYST_DEBUG=0 prove --lib lib t
 110
 111 During the C<t/02pod> and C<t/03podcoverage> tests, you might notice the
 112 C<all skipped: set TEST_POD to enable this test> warning message.  To
 113 execute the Pod-related tests, add C<TEST_POD=1> to the C<prove>
 114 command:
 115
 116     $ CATALYST_DEBUG=0 TEST_POD=1 prove --lib lib t
 117
 118 If you omitted the Pod comments from any of the methods that were
 119 inserted, you might have to go back and fix them to get these tests to
 120 pass. :-)
 121
 122 Another useful option is the C<verbose> (C<-v>) option to C<prove>.  It
 123 prints the name of each test case as it is being run:
 124
 125     $ CATALYST_DEBUG=0 TEST_POD=1 prove --lib lib -v t
 126
 127
 128
 129 =head1 RUNNING A SINGLE TEST
 130
 131 You can also run a single script by appending its name to the C<prove>
 132 command. For example:
 133
 134     $ CATALYST_DEBUG=0 prove --lib lib t/01app.t
 135
 136 Note that you can also run tests directly from Perl without C<prove>.
 137 For example:
 138
 139     $ CATALYST_DEBUG=0 perl -Ilib t/01app.t
 140
 141
 142 =head1 ADDING YOUR OWN TEST SCRIPT
 143
 144 Although the Catalyst helper scripts provide a basic level of checks
 145 "for free," testing can become significantly more helpful when you write
 146 your own script to exercise the various parts of your application.  The
 147 L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> module
 148 is very popular for writing these sorts of test cases.  This module
 149 extends L<Test::WWW::Mechanize|Test::WWW::Mechanize> (and therefore
 150 L<WWW::Mechanize|WWW::Mechanize>) to allow you to automate the action of
 151 a user "clicking around" inside your application.  It gives you all the
 152 benefits of testing on a live system without the messiness of having to
 153 use an actual web server.
 154
 155 To create a sample test case, open the C<t/live_app01.t> file in your
 156 editor and enter the following:
 157
 158     #!/usr/bin/perl
 159
 160     use strict;
 161     use warnings;
 162
 163     # Load testing framework and use 'no_plan' to dynamically pick up all tests.  Better
 164     # to replace "'no_plan'" with "tests => 30" so it knows exactly how many tests need
 165     # to be run (and will tell you if not), but 'no_plan' is nice for quick & dirty tests
 166     use Test::More 'no_plan';
 167
 168     # Need to specify the name of your app as arg on next line
 169     # Can also do:
 170     #   use Test::WWW::Mechanize::Catalyst "MyApp";
 171     use ok "Test::WWW::Mechanize::Catalyst" => "MyApp";
 172
 173
 174     # Create two 'user agents' to simulate two different users ('test01' & 'test02')
 175     my $ua1 = Test::WWW::Mechanize::Catalyst->new;
 176     my $ua2 = Test::WWW::Mechanize::Catalyst->new;
 177
 178     # Use a simplified for loop to do tests that are common to both users
 179     # Use get_ok() to make sure we can hit the base URL
 180     # Second arg = optional description of test (will be displayed for failed tests)
 181     # Note that in test scripts you send everything to 'http://localhost'
 182     $_->get_ok("http://localhost/", "Check redirect of base URL") for $ua1, $ua2;
 183     # Use title_is() to check the contents of the <title>...</title> tags
 184     $_->title_is("Login", "Check for login title") for $ua1, $ua2;
 185     # Use content_contains() to match on test in the html body
 186     $_->content_contains("You need to log in to use this application",
 187         "Check we are NOT logged in") for $ua1, $ua2;
 188
 189     # Log in as each user
 190     $ua1->get_ok("http://localhost/login?username=test01&password=mypass", "Login 'test01'");
 191     $ua2->get_ok("http://localhost/login?username=test02&password=mypass", "Login 'test02'");
 192
 193     # Go back to the login page and it should show that we are already logged in
 194     $_->get_ok("http://localhost/login", "Return to '/login'") for $ua1, $ua2;
 195     $_->title_is("Login", "Check for login page") for $ua1, $ua2;
 196     $_->content_contains("Please Note: You are already logged in as ",
 197         "Check we ARE logged in" ) for $ua1, $ua2;
 198
 199     # 'Click' the 'Logout' link
 200     $_->follow_link_ok({n => 1}, "Logout via first link on page") for $ua1, $ua2;
 201     $_->title_is("Login", "Check for login title") for $ua1, $ua2;
 202     $_->content_contains("You need to log in to use this application",
 203         "Check we are NOT logged in") for $ua1, $ua2;
 204
 205     # Log back in
 206     $ua1->get_ok("http://localhost/login?username=test01&password=mypass", "Login 'test01'");
 207     $ua2->get_ok("http://localhost/login?username=test02&password=mypass", "Login 'test02'");
 208     # Should be at the Book List page... do some checks to confirm
 209     $_->title_is("Book List", "Check for book list title") for $ua1, $ua2;
 210
 211     $ua1->get_ok("http://localhost/books/list", "'test01' book list");
 212     $ua1->get_ok("http://localhost/login", "Login Page");
 213     $ua1->get_ok("http://localhost/books/list", "'test01' book list");
 214
 215     $_->content_contains("Book List", "Check for book list title") for $ua1, $ua2;
 216     # Make sure the appropriate logout buttons are displayed
 217     $_->content_contains("/logout\">Logout</a>",
 218         "Both users should have a 'User Logout'") for $ua1, $ua2;
 219     $ua1->content_contains("/books/form_create\">Create</a>",
 220         "Only 'test01' should have a create link");
 221
 222     $ua1->get_ok("http://localhost/books/list", "View book list as 'test01'");
 223
 224     # User 'test01' should be able to create a book with the "formless create" URL
 225     $ua1->get_ok("http://localhost/books/url_create/TestTitle/2/4",
 226         "'test01' formless create");
 227     $ua1->title_is("Book Created", "Book created title");
 228     $ua1->content_contains("Added book 'TestTitle' by 'Stevens'", "Check added OK");
 229     $ua1->content_contains("a rating of 2.", "Check rating added");
 230
 231     # Make sure the new book shows in the list
 232     $ua1->get_ok("http://localhost/books/list", "'test01' book list");
 233     $ua1->title_is("Book List", "Check logged in and at book list");
 234     $ua1->content_contains("Book List", "Book List page test");
 235     $ua1->content_contains("TestTitle", "Look for 'TestTitle'");
 236
 237     # Make sure the new book can be deleted
 238     # Get all the Delete links on the list page
 239     my @delLinks = $ua1->find_all_links(text => 'Delete');
 240     # Use the final link to delete the last book
 241     $ua1->get_ok($delLinks[$#delLinks]->url, 'Delete last book');
 242     # Check that delete worked
 243     $ua1->content_contains("Book List", "Book List page test");
 244     $ua1->content_contains("Book deleted.", "Book was deleted");
 245
 246     # User 'test02' should not be able to add a book
 247     $ua2->get_ok("http://localhost/books/url_create/TestTitle2/2/5", "'test02' add");
 248     $ua2->content_contains("Unauthorized!", "Check 'test02' cannot add");
 249
 250 The C<live_app.t> test cases uses copious comments to explain each step
 251 of the process.  In addition to the techniques shown here, there are a
 252 variety of other methods available in
 253 L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> (for
 254 example, regex-based matching).  Consult the documentation for more
 255 detail.
 256
 257 B<TIP>: For I<unit tests> vs. the "full application tests" approach used
 258 by L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst>, see
 259 L<Catalyst::Test|Catalyst::Test>.
 260
 261 B<Note:> The test script does not test the C<form_create> and
 262 C<form_create_do> actions.  That is left as an exercise for the reader
 263 (you should be able to complete that logic using the existing code as a
 264 template).
 265
 266 To run the new test script, use a command such as:
 267
 268     $ CATALYST_DEBUG=0 prove --lib lib -v t/live_app01.t
 269
 270 or
 271
 272     $ DBIX_CLASS_STORAGE_DBI_DEBUG=0 CATALYST_DEBUG=0 prove --lib lib -v t/live_app01.t
 273
 274 Experiment with the C<DBIX_CLASS_STORAGE_DBI_DEBUG>, C<CATALYST_DEBUG>
 275 and C<-v> settings.  If you find that there are errors, use the
 276 techniques discussed in the "Catalyst Debugging" section (Part 6) to
 277 isolate and fix the problem.
 278
 279 If you want to run the test case under the Perl interactive debugger,
 280 try a command such as:
 281
 282     $ DBIX_CLASS_STORAGE_DBI_DEBUG=0 CATALYST_DEBUG=0 perl -d -Ilib t/live_app01.t
 283
 284 Note that although the tutorial uses a single custom test case for
 285 simplicity, you may wish to break your tests into different files for
 286 better organization.
 287
 288
 289
 290 =head1 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
 291
 292 You may wish to leverage the techniques discussed in this tutorial to
 293 maintain both a "production database" for your live application and a
 294 "testing database" for your test cases.  One advantage to
 295 L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> is that
 296 it runs your full application; however, this can complicate things when
 297 you want to support multiple databases.  One solution is to allow the
 298 database specification to be overridden with an environment variable.
 299 For example, open C<lib/MyApp/Model/MyAppDB.pm> in your editor and
 300 change the C<__PACKAGE__-E<gt>config(...> declaration to resemble:
 301
 302     my $dsn = $ENV{MYAPP_DSN} ||= 'dbi:SQLite:myapp.db';
 303     __PACKAGE__->config(
 304         schema_class => 'MyAppDB',
 305         connect_info => [
 306             $dsn,
 307             '',
 308             '',
 309             { AutoCommit => 1 },
 310
 311         ],
 312     );
 313
 314 Then, when you run your test case, you can use commands such as:
 315
 316     $ cp myapp.db myappTEST.db
 317     $ CATALYST_DEBUG=0 MYAPP_DSN="dbi:SQLite:myappTEST.db" prove --lib lib -v t/live_app01.t
 318
 319 This will modify the DSN only while the test case is running.  If you
 320 launch your normal application without the C<MYAPP_DSN> environment
 321 variable defined, it will default to the same C<dbi:SQLite:myapp.db> as
 322 before.
 323
 324
 325
 326 =head1 AUTHOR
 327
 328 Kennedy Clark, C<hkclark@gmail.com>
 329
 330 Please report any errors, issues or suggestions to the author.
 331
 332 Copyright 2006, Kennedy Clark, under Creative Commons License
 333 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
 334
 335 Version: .94
 336