Remove now old mention of "used more than once" errors
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial / 08_Testing.pod
d442cc9f 1=head1 NAME
3ab6187c 3Catalyst::Manual::Tutorial::08_Testing - Catalyst Tutorial - Chapter 8: Testing
d442cc9f 4
6=head1 OVERVIEW
4b4d3884 8This is B<Chapter 8 of 10> for the Catalyst tutorial.
d442cc9f 9
10L<Tutorial Overview|Catalyst::Manual::Tutorial>
12=over 4
14=item 1
3ab6187c 16L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
d442cc9f 17
18=item 2
3ab6187c 20L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
d442cc9f 21
22=item 3
3ab6187c 24L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
d442cc9f 25
26=item 4
3ab6187c 28L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
d442cc9f 29
30=item 5
3ab6187c 32L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
d442cc9f 33
34=item 6
3ab6187c 36L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
d442cc9f 37
38=item 7
3ab6187c 40L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
d442cc9f 41
42=item 8
3ab6187c 44B<08_Testing>
d442cc9f 45
46=item 9
3ab6187c 48L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
3533daff 49
50=item 10
3ab6187c 52L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
d442cc9f 53
3533daff 56
d442cc9f 57=head1 DESCRIPTION
4b4d3884 59You may have noticed that the Catalyst Helper scripts automatically
60create basic C<.t> test scripts under the C<t> directory. This
61chapter of the tutorial briefly looks at how these tests can be used
3b1fa91b 62not only to ensure that your application is working correctly at the
4b4d3884 63present time, but also provide automated regression testing as you
64upgrade various pieces of your application over time.
d442cc9f 65
4d63a0d5 66You can check out the source code for this example from the Catalyst
67Subversion repository as per the instructions in
3ab6187c 68L<Catalyst::Manual::Tutorial::01_Intro|Catalyst::Manual::Tutorial::01_Intro>.
1390ef0e 69
3b1fa91b 70For an excellent introduction to learning the many benefits of testing
71your Perl applications and modules, you might want to read 'Perl Testing:
72A Developer's Notebook' by Ian Langworth and chromatic.
d442cc9f 74
77There are a variety of ways to run Catalyst and Perl tests (for example,
78C<perl Makefile.PL> and C<make test>), but one of the easiest is with the
79C<prove> command. For example, to run all of the tests in the C<t>
80directory, enter:
da59dbea 82 $ prove -wl t
d442cc9f 83
028b4e1a 84There will be a lot of output because we have the C<-Debug> flag
85enabled in C<lib/> (see the C<CATALYST_DEBUG=0> tip below for
86a quick and easy way to reduce the clutter). Look for lines like this
87for errors:
3533daff 88
89 # Failed test 'Request should succeed'
3b1fa91b 90 # at t/controller_Books.t line 8.
3533daff 91 # Looks like you failed 1 test of 3.
93The redirection used by the Authentication plugins will cause several
94failures in the default tests. You can fix this by making the following
acbd7bdd 971) Change the line in C<t/01app.t> that reads:
d442cc9f 98
99 ok( request('/')->is_success, 'Request should succeed' );
103 ok( request('/login')->is_success, 'Request should succeed' );
3b1fa91b 1052) Change the line in C<t/controller_Logout.t> that reads:
107 ok( request('/logout')->is_success, 'Request should succeed' );
111 ok( request('/logout')->is_redirect, 'Request should succeed' );
1133) Change the line in C<t/controller_Books.t> that reads:
115 ok( request('/books')->is_success, 'Request should succeed' );
119 ok( request('/books')->is_redirect, 'Request should succeed' );
d442cc9f 120
3b1fa91b 1214) Add the following statement to the top of C<t/view_TT.t>:
d442cc9f 122
3b1fa91b 123 use MyApp;
6a72d1bf 124
d442cc9f 125As you can see in the C<prove> command line above, the C<--lib> option
126is used to set the location of the Catalyst C<lib> directory. With this
127command, you will get all of the usual development server debug output,
128something most people prefer to disable while running tests cases.
129Although you can edit the C<lib/> to comment out the C<-Debug>
130plugin, it's generally easier to simply set the C<CATALYST_DEBUG=0>
131environment variable. For example:
da59dbea 133 $ CATALYST_DEBUG=0 prove -wl t
d442cc9f 134
135During the C<t/02pod> and C<t/03podcoverage> tests, you might notice the
136C<all skipped: set TEST_POD to enable this test> warning message. To
137execute the Pod-related tests, add C<TEST_POD=1> to the C<prove>
da59dbea 140 $ CATALYST_DEBUG=0 TEST_POD=1 prove -wl t
d442cc9f 141
142If you omitted the Pod comments from any of the methods that were
143inserted, you might have to go back and fix them to get these tests to
144pass. :-)
146Another useful option is the C<verbose> (C<-v>) option to C<prove>. It
147prints the name of each test case as it is being run:
da59dbea 149 $ CATALYST_DEBUG=0 TEST_POD=1 prove -vwl t
d442cc9f 150
3533daff 151
d442cc9f 152=head1 RUNNING A SINGLE TEST
154You can also run a single script by appending its name to the C<prove>
155command. For example:
da59dbea 157 $ CATALYST_DEBUG=0 prove -wl t/01app.t
d442cc9f 158
3533daff 159Also note that you can also run tests directly from Perl without C<prove>.
d442cc9f 160For example:
da59dbea 162 $ CATALYST_DEBUG=0 perl -w -Ilib t/01app.t
d442cc9f 163
3533daff 164
d442cc9f 165=head1 ADDING YOUR OWN TEST SCRIPT
167Although the Catalyst helper scripts provide a basic level of checks
168"for free," testing can become significantly more helpful when you write
169your own script to exercise the various parts of your application. The
170L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> module
171is very popular for writing these sorts of test cases. This module
172extends L<Test::WWW::Mechanize|Test::WWW::Mechanize> (and therefore
173L<WWW::Mechanize|WWW::Mechanize>) to allow you to automate the action of
174a user "clicking around" inside your application. It gives you all the
175benefits of testing on a live system without the messiness of having to
176use an actual web server, and a real person to do the clicking.
178To create a sample test case, open the C<t/live_app01.t> file in your
179editor and enter the following:
181 #!/usr/bin/perl
183 use strict;
184 use warnings;
da59dbea 185 use Test::More;
d442cc9f 186
187 # Need to specify the name of your app as arg on next line
188 # Can also do:
189 # use Test::WWW::Mechanize::Catalyst "MyApp";
191 use ok "Test::WWW::Mechanize::Catalyst" => "MyApp";
193 # Create two 'user agents' to simulate two different users ('test01' & 'test02')
194 my $ua1 = Test::WWW::Mechanize::Catalyst->new;
195 my $ua2 = Test::WWW::Mechanize::Catalyst->new;
197 # Use a simplified for loop to do tests that are common to both users
198 # Use get_ok() to make sure we can hit the base URL
199 # Second arg = optional description of test (will be displayed for failed tests)
200 # Note that in test scripts you send everything to 'http://localhost'
201 $_->get_ok("http://localhost/", "Check redirect of base URL") for $ua1, $ua2;
202 # Use title_is() to check the contents of the <title>...</title> tags
203 $_->title_is("Login", "Check for login title") for $ua1, $ua2;
204 # Use content_contains() to match on text in the html body
205 $_->content_contains("You need to log in to use this application",
206 "Check we are NOT logged in") for $ua1, $ua2;
208 # Log in as each user
209 # Specify username and password on the URL
210 $ua1->get_ok("http://localhost/login?username=test01&password=mypass", "Login 'test01'");
2a6eb5f9 211 # Could make user2 like user1 above, but use the form to show another way
212 $ua2->submit_form(
213 fields => {
214 username => 'test02',
215 password => 'mypass',
216 });
d442cc9f 217
218 # Go back to the login page and it should show that we are already logged in
219 $_->get_ok("http://localhost/login", "Return to '/login'") for $ua1, $ua2;
220 $_->title_is("Login", "Check for login page") for $ua1, $ua2;
221 $_->content_contains("Please Note: You are already logged in as ",
222 "Check we ARE logged in" ) for $ua1, $ua2;
224 # 'Click' the 'Logout' link (see also 'text_regex' and 'url_regex' options)
028b4e1a 225 $_->follow_link_ok({n => 4}, "Logout via first link on page") for $ua1, $ua2;
d442cc9f 226 $_->title_is("Login", "Check for login title") for $ua1, $ua2;
227 $_->content_contains("You need to log in to use this application",
228 "Check we are NOT logged in") for $ua1, $ua2;
230 # Log back in
231 $ua1->get_ok("http://localhost/login?username=test01&password=mypass", "Login 'test01'");
232 $ua2->get_ok("http://localhost/login?username=test02&password=mypass", "Login 'test02'");
233 # Should be at the Book List page... do some checks to confirm
234 $_->title_is("Book List", "Check for book list title") for $ua1, $ua2;
236 $ua1->get_ok("http://localhost/books/list", "'test01' book list");
237 $ua1->get_ok("http://localhost/login", "Login Page");
238 $ua1->get_ok("http://localhost/books/list", "'test01' book list");
240 $_->content_contains("Book List", "Check for book list title") for $ua1, $ua2;
241 # Make sure the appropriate logout buttons are displayed
fbbb9084 242 $_->content_contains("/logout\">User Logout</a>",
d442cc9f 243 "Both users should have a 'User Logout'") for $ua1, $ua2;
6290bf87 244 $ua1->content_contains("/books/form_create\">Admin Create</a>",
87058ad4 245 "'test01' should have a create link");
246 $ua2->content_lacks("/books/form_create\">Admin Create</a>",
247 "'test02' should NOT have a create link");
d442cc9f 248
249 $ua1->get_ok("http://localhost/books/list", "View book list as 'test01'");
251 # User 'test01' should be able to create a book with the "formless create" URL
252 $ua1->get_ok("http://localhost/books/url_create/TestTitle/2/4",
253 "'test01' formless create");
254 $ua1->title_is("Book Created", "Book created title");
255 $ua1->content_contains("Added book 'TestTitle'", "Check title added OK");
256 $ua1->content_contains("by 'Stevens'", "Check author added OK");
257 $ua1->content_contains("with a rating of 2.", "Check rating added");
258 # Try a regular expression to combine the previous 3 checks & account for whitespace
259 $ua1->content_like(qr/Added book 'TestTitle'\s+by 'Stevens'\s+with a rating of 2./, "Regex check");
261 # Make sure the new book shows in the list
262 $ua1->get_ok("http://localhost/books/list", "'test01' book list");
263 $ua1->title_is("Book List", "Check logged in and at book list");
264 $ua1->content_contains("Book List", "Book List page test");
265 $ua1->content_contains("TestTitle", "Look for 'TestTitle'");
267 # Make sure the new book can be deleted
268 # Get all the Delete links on the list page
269 my @delLinks = $ua1->find_all_links(text => 'Delete');
270 # Use the final link to delete the last book
271 $ua1->get_ok($delLinks[$#delLinks]->url, 'Delete last book');
272 # Check that delete worked
273 $ua1->content_contains("Book List", "Book List page test");
274 $ua1->content_contains("Book deleted", "Book was deleted");
276 # User 'test02' should not be able to add a book
277 $ua2->get_ok("http://localhost/books/url_create/TestTitle2/2/5", "'test02' add");
278 $ua2->content_contains("Unauthorized!", "Check 'test02' cannot add");
0a2a4a5a 279
da59dbea 280 done_testing;
d442cc9f 282The C<live_app.t> test cases uses copious comments to explain each step
283of the process. In addition to the techniques shown here, there are a
284variety of other methods available in
285L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> (for
286example, regex-based matching). Consult the documentation for more
289B<TIP>: For I<unit tests> vs. the "full application tests" approach used
290by L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst>, see
293B<Note:> The test script does not test the C<form_create> and
294C<form_create_do> actions. That is left as an exercise for the reader
295(you should be able to complete that logic using the existing code as a
298To run the new test script, use a command such as:
da59dbea 300 $ CATALYST_DEBUG=0 prove -vwl t/live_app01.t
d442cc9f 301
da59dbea 304 $ DBIC_TRACE=0 CATALYST_DEBUG=0 prove -vwl t/live_app01.t
d442cc9f 305
4b4d3884 306Experiment with the C<DBIC_TRACE>, C<CATALYST_DEBUG> and C<-v>
307settings. If you find that there are errors, use the techniques
308discussed in the "Catalyst Debugging" section (Chapter 7) to isolate
309and fix any problems.
d442cc9f 310
311If you want to run the test case under the Perl interactive debugger,
312try a command such as:
314 $ DBIC_TRACE=0 CATALYST_DEBUG=0 perl -d -Ilib t/live_app01.t
316Note that although this tutorial uses a single custom test case for
317simplicity, you may wish to break your tests into different files for
318better organization.
320B<TIP:> If you have a test case that fails, you will receive an error
321similar to the following:
323 # Failed test 'Check we are NOT logged in'
324 # in t/live_app01.t at line 31.
325 # searched: "\x{0a}<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Tran"...
326 # can't find: "You need to log in to use this application."
328Unfortunately, this only shows us the first 50 characters of the HTML
329returned by the request -- not enough to determine where the problem
330lies. A simple technique that can be used in such situations is to
331temporarily insert a line similar to the following right after the
332failed test:
6daaedc0 334 diag $ua1->content;
d442cc9f 335
336This will cause the full HTML returned by the request to be displayed.
fbbb9084 338Another approach to see the full HTML content at the failure point in
339a series of tests would be to insert a "C<$DB::single=1;> right above
340the location of the failure and run the test under the perl debugger
341(with C<-d>) as shown above. Then you can use the debugger to explore
342the state of the application right before or after the failure.
d442cc9f 344
347You may wish to leverage the techniques discussed in this tutorial to
348maintain both a "production database" for your live application and a
349"testing database" for your test cases. One advantage to
350L<Test::WWW::Mechanize::Catalyst|Test::WWW::Mechanize::Catalyst> is that
351it runs your full application; however, this can complicate things when
352you want to support multiple databases. One solution is to allow the
353database specification to be overridden with an environment variable.
d0496197 354For example, open C<lib/MyApp/Model/> in your editor and
d442cc9f 355change the C<__PACKAGE__-E<gt>config(...> declaration to resemble:
357 my $dsn = $ENV{MYAPP_DSN} ||= 'dbi:SQLite:myapp.db';
358 __PACKAGE__->config(
d0496197 359 schema_class => 'MyApp::Schema',
0a2a4a5a 360
da59dbea 361 connect_info => {
362 dsn => $dsn,
0a2a4a5a 363 user => '',
364 password => '',
365 on_connect_do => q{PRAGMA foreign_keys = ON},
366 }
367 );
d442cc9f 368
369Then, when you run your test case, you can use commands such as:
371 $ cp myapp.db myappTEST.db
da59dbea 372 $ CATALYST_DEBUG=0 MYAPP_DSN="dbi:SQLite:myappTEST.db" prove -vwl t/live_app01.t
d442cc9f 373
374This will modify the DSN only while the test case is running. If you
375launch your normal application without the C<MYAPP_DSN> environment
376variable defined, it will default to the same C<dbi:SQLite:myapp.db> as
380=head1 AUTHOR
382Kennedy Clark, C<>
384Please report any errors, issues or suggestions to the author. The
385most recent version of the Catalyst Tutorial can be found at
59884771 386L<>.
d442cc9f 387
45c7830f 388Copyright 2006-2008, Kennedy Clark, under Creative Commons License
8482d557 389(L<>).
d442cc9f 390