X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2F08_Testing.pod;h=30dc008ed538e8303dcc796d6d352c8b453ebda3;hp=b247014ba20a0e083dbd43d13b372debac17d142;hb=477a6d5b13f55eb335979812080e4a11217f19d6;hpb=e541538422e839971d0c91c47ea19029de01cfa5 diff --git a/lib/Catalyst/Manual/Tutorial/08_Testing.pod b/lib/Catalyst/Manual/Tutorial/08_Testing.pod index b247014..30dc008 100644 --- a/lib/Catalyst/Manual/Tutorial/08_Testing.pod +++ b/lib/Catalyst/Manual/Tutorial/08_Testing.pod @@ -56,41 +56,42 @@ L =head1 DESCRIPTION -You may have noticed that the Catalyst Helper scripts automatically -create basic C<.t> test scripts under the C directory. This -chapter of the tutorial briefly looks at how these tests can be used -not only to ensure that your application is working correctly at the -present time, but also provide automated regression testing as you -upgrade various pieces of your application over time. - -You can check out the source code for this example from the Catalyst -Subversion repository as per the instructions in -L. +You may have noticed that the Catalyst Helper scripts automatically +create basic C<.t> test scripts under the C directory. This chapter +of the tutorial briefly looks at how these tests can be used not only to +ensure that your application is working correctly at the present time, +but also provide automated regression testing as you upgrade various +pieces of your application over time. + +Source code for the tutorial in included in the F +directory of the Tutorial Virtual machine (one subdirectory per +chapter). There are also instructions for downloading the code in +L. For an excellent introduction to learning the many benefits of testing -your Perl applications and modules, you might want to read 'Perl Testing: -A Developer's Notebook' by Ian Langworth and chromatic. +your Perl applications and modules, you might want to read 'Perl +Testing: A Developer's Notebook' by Ian Langworth and chromatic. =head1 RUNNING THE "CANNED" CATALYST TESTS There are a variety of ways to run Catalyst and Perl tests (for example, -C and C), but one of the easiest is with the -C command. For example, to run all of the tests in the C +C and C), but one of the easiest is with +the C command. For example, to run all of the tests in the C directory, enter: $ prove -wl t -There will be a lot of output because we have the C<-Debug> flag -enabled in C (see the C tip below for -a quick and easy way to reduce the clutter). Look for lines like this -for errors: +There will be a lot of output because we have the C<-Debug> flag enabled +in C (see the C tip below for a quick +and easy way to reduce the clutter). Look for lines like this for +errors: # Failed test 'Request should succeed' # at t/controller_Books.t line 8. # Looks like you failed 1 test of 3. -The redirection used by the Authentication plugins will cause several +The redirection used by the Authentication plugins will cause several failures in the default tests. You can fix this by making the following changes: @@ -118,17 +119,17 @@ to: ok( request('/books')->is_redirect, 'Request should succeed' ); -4) Add the following statement to the top of C: +4) Add the following statement to the top of C: use MyApp; -As you can see in the C command line above, the C<--lib> option -is used to set the location of the Catalyst C directory. With this -command, you will get all of the usual development server debug output, -something most people prefer to disable while running tests cases. -Although you can edit the C to comment out the C<-Debug> -plugin, it's generally easier to simply set the C -environment variable. For example: +As you can see in the C command line above, the C<-l> option (or +C<--lib> if you prefer) is used to set the location of the Catalyst +C directory. With this command, you will get all of the usual +development server debug output, something most people prefer to disable +while running tests cases. Although you can edit the C to +comment out the C<-Debug> plugin, it's generally easier to simply set +the C environment variable. For example: $ CATALYST_DEBUG=0 prove -wl t @@ -146,7 +147,7 @@ pass. :-) Another useful option is the C (C<-v>) option to C. It prints the name of each test case as it is being run: - $ CATALYST_DEBUG=0 TEST_POD=1 prove -vwl t + $ CATALYST_DEBUG=0 prove -vwl t =head1 RUNNING A SINGLE TEST @@ -156,8 +157,8 @@ command. For example: $ CATALYST_DEBUG=0 prove -wl t/01app.t -Also note that you can also run tests directly from Perl without C. -For example: +Also note that you can also run tests directly from Perl without +C. For example: $ CATALYST_DEBUG=0 perl -w -Ilib t/01app.t @@ -166,11 +167,10 @@ For example: Although the Catalyst helper scripts provide a basic level of checks "for free," testing can become significantly more helpful when you write -your own script to exercise the various parts of your application. The -L module -is very popular for writing these sorts of test cases. This module -extends L (and therefore -L) to allow you to automate the action of +your own tests to exercise the various parts of your application. The +L module is very popular for writing +these sorts of test cases. This module extends L +(and therefore L) to allow you to automate the action of a user "clicking around" inside your application. It gives you all the benefits of testing on a live system without the messiness of having to use an actual web server, and a real person to do the clicking. @@ -178,7 +178,7 @@ use an actual web server, and a real person to do the clicking. To create a sample test case, open the C file in your editor and enter the following: - #!/usr/bin/perl + #!/usr/bin/env perl use strict; use warnings; @@ -189,7 +189,7 @@ editor and enter the following: # use Test::WWW::Mechanize::Catalyst "MyApp"; BEGIN { use_ok("Test::WWW::Mechanize::Catalyst" => "MyApp") } - + # Create two 'user agents' to simulate two different users ('test01' & 'test02') my $ua1 = Test::WWW::Mechanize::Catalyst->new; my $ua2 = Test::WWW::Mechanize::Catalyst->new; @@ -228,8 +228,10 @@ editor and enter the following: "Check we are NOT logged in") for $ua1, $ua2; # Log back in - $ua1->get_ok("http://localhost/login?username=test01&password=mypass", "Login 'test01'"); - $ua2->get_ok("http://localhost/login?username=test02&password=mypass", "Login 'test02'"); + $ua1->get_ok("http://localhost/login?username=test01&password=mypass", + "Login 'test01'"); + $ua2->get_ok("http://localhost/login?username=test02&password=mypass", + "Login 'test02'"); # Should be at the Book List page... do some checks to confirm $_->title_is("Book List", "Check for book list title") for $ua1, $ua2; @@ -256,7 +258,8 @@ editor and enter the following: $ua1->content_contains("by 'Stevens'", "Check author added OK"); $ua1->content_contains("with a rating of 2.", "Check rating added"); # Try a regular expression to combine the previous 3 checks & account for whitespace - $ua1->content_like(qr/Added book 'TestTitle'\s+by 'Stevens'\s+with a rating of 2./, "Regex check"); + $ua1->content_like(qr/Added book 'TestTitle'\s+by 'Stevens'\s+with a rating of 2./, + "Regex check"); # Make sure the new book shows in the list $ua1->get_ok("http://localhost/books/list", "'test01' book list"); @@ -271,7 +274,7 @@ editor and enter the following: $ua1->get_ok($delLinks[$#delLinks]->url, 'Delete last book'); # Check that delete worked $ua1->content_contains("Book List", "Book List page test"); - $ua1->content_contains("Book deleted", "Book was deleted"); + $ua1->content_like(qr/Deleted book \d+/, "Deleted book #"); # User 'test02' should not be able to add a book $ua2->get_ok("http://localhost/books/url_create/TestTitle2/2/5", "'test02' add"); @@ -281,14 +284,13 @@ editor and enter the following: The C test cases uses copious comments to explain each step of the process. In addition to the techniques shown here, there are a -variety of other methods available in -L (for -example, regex-based matching). Consult the documentation for more -detail. +variety of other methods available in L +(for example, regex-based matching). Consult +L, L, +L, and L for more detail. B: For I vs. the "full application tests" approach used -by L, see -L. +by L, see L. B The test script does not test the C and C actions. That is left as an exercise for the reader @@ -303,10 +305,10 @@ or $ DBIC_TRACE=0 CATALYST_DEBUG=0 prove -vwl t/live_app01.t -Experiment with the C, C and C<-v> -settings. If you find that there are errors, use the techniques -discussed in the "Catalyst Debugging" section (Chapter 7) to isolate -and fix any problems. +Experiment with the C, C and C<-v> settings. +If you find that there are errors, use the techniques discussed in the +"Catalyst Debugging" section (Chapter 7) to isolate and fix any +problems. If you want to run the test case under the Perl interactive debugger, try a command such as: @@ -327,19 +329,19 @@ similar to the following: Unfortunately, this only shows us the first 50 characters of the HTML returned by the request -- not enough to determine where the problem -lies. A simple technique that can be used in such situations is to -temporarily insert a line similar to the following right after the +lies. A simple technique that can be used in such situations is to +temporarily insert a line similar to the following right after the failed test: diag $ua1->content; This will cause the full HTML returned by the request to be displayed. -Another approach to see the full HTML content at the failure point in -a series of tests would be to insert a "C<$DB::single=1;> right above -the location of the failure and run the test under the perl debugger -(with C<-d>) as shown above. Then you can use the debugger to explore -the state of the application right before or after the failure. +Another approach to see the full HTML content at the failure point in a +series of tests would be to insert a "C<$DB::single=1;> right above the +location of the failure and run the test under the Perl debugger (with +C<-d>) as shown above. Then you can use the debugger to explore the +state of the application right before or after the failure. =head1 SUPPORTING BOTH PRODUCTION AND TEST DATABASES @@ -347,16 +349,16 @@ the state of the application right before or after the failure. You may wish to leverage the techniques discussed in this tutorial to maintain both a "production database" for your live application and a "testing database" for your test cases. One advantage to -L is that -it runs your full application; however, this can complicate things when -you want to support multiple databases. +L is that it runs your full application; +however, this can complicate things when you want to support multiple +databases. =head2 DATABASE CONFIG SWITCHING IN YOUR MODEL CLASS -One solution is to allow the -database specification to be overridden with an environment variable. -For example, open C in your editor and -change the C<__PACKAGE__-Econfig(...> declaration to resemble: +One solution is to allow the database specification to be overridden +with an environment variable. For example, open +C in your editor and change the +C<__PACKAGE__-Econfig(...> declaration to resemble: my $dsn = $ENV{MYAPP_DSN} ||= 'dbi:SQLite:myapp.db'; __PACKAGE__->config( @@ -380,21 +382,25 @@ launch your normal application without the C environment variable defined, it will default to the same C as before. + =head2 DATABASE CONFIG SWITCHING USING MULTIPLE CONFIG FILES -By utilizing Ls functionality for loading -multiple config files based on environment variables you can override your -default (production) database connection settings. +L has functionality to load loading +multiple config files based on environment variablesi, allowing you to +override your default (production) database connection settings during +development (or vice versa). -Setting C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> to 'testing' in your test script -results in loading of an additional config file named myapp_testing.conf after -myapp.conf which will override any parameters in myapp.conf. +Setting C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> to 'testing' in your test +script results in loading of an additional config file named +C after C which will override any +parameters in C. -You should set the environment variable in the BEGIN block of your test script -to make sure it's set before your Catalyst application is started. +You should set the environment variable in the BEGIN block of your test +script to make sure it's set before your Catalyst application is +started. -The following is an example for a config and test script for a DBIx::Class -model named MyDB and a controller named Foo: +The following is an example for a config and test script for a +DBIx::Class model named MyDB and a controller named Foo: myapp_testing.conf: @@ -410,29 +416,33 @@ t/controller_Foo.t: use strict; use warnings; use Test::More; - + BEGIN { $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX } = 'testing'; } - + eval "use Test::WWW::Mechanize::Catalyst 'MyApp'"; plan $@ ? ( skip_all => 'Test::WWW::Mechanize::Catalyst required' ) : ( tests => 2 ); - + ok( my $mech = Test::WWW::Mechanize::Catalyst->new, 'Created mech object' ); - + $mech->get_ok( 'http://localhost/foo' ); +You can jump to the next chapter of the tutorial here: +L + + =head1 AUTHOR Kennedy Clark, C -Please report any errors, issues or suggestions to the author. The -most recent version of the Catalyst Tutorial can be found at -L. +Feel free to contact the author for any errors or suggestions, but the +best way to report issues is via the CPAN RT Bug system at +L. -Copyright 2006-2010, Kennedy Clark, under Creative Commons License +Copyright 2006-2011, Kennedy Clark, under the +Creative Commons Attribution Share-Alike License Version 3.0 (L). -