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=f21f5f6da1630dece21169d4122f17b927e830e8;hb=477a6d5b13f55eb335979812080e4a11217f19d6;hpb=da59dbea96454dbc53dc7bb5a813849bb35c6ab8 diff --git a/lib/Catalyst/Manual/Tutorial/08_Testing.pod b/lib/Catalyst/Manual/Tutorial/08_Testing.pod index f21f5f6..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,43 +119,20 @@ 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 -B Depending on the versions of various modules you have -installed, you might get some C warnings -- you can -ignore these. If you want to eliminate the warnings, you can -edit C to disable and then re-enable warnings -are the C line in C. -You can locate where C is located with the -following command (it's probably in a place similar to -C): - - perldoc -l Template::Base - -Edit the file and modify C to match: - - ... - { no strict qw( refs ); - # Disable warnings - no warnings; - $argnames = \@{"$class\::BASEARGS"} || [ ]; - # Turn warnings back on - use warnings; - } - ... - During the C and C tests, you might notice the C warning message. To execute the Pod-related tests, add C to the C @@ -169,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 @@ -179,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 @@ -189,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. @@ -201,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; @@ -211,8 +188,8 @@ editor and enter the following: # Can also do: # use Test::WWW::Mechanize::Catalyst "MyApp"; - use ok "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; @@ -251,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; @@ -279,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"); @@ -294,24 +274,23 @@ 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"); $ua2->content_contains("Unauthorized!", "Check 'test02' cannot add"); - + done_testing; 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 @@ -326,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: @@ -350,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 @@ -370,20 +349,28 @@ 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. 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: +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: my $dsn = $ENV{MYAPP_DSN} ||= 'dbi:SQLite:myapp.db'; __PACKAGE__->config( schema_class => 'MyApp::Schema', - + connect_info => { dsn => $dsn, - ... + user => '', + password => '', + on_connect_do => q{PRAGMA foreign_keys = ON}, + } + ); Then, when you run your test case, you can use commands such as: @@ -396,14 +383,66 @@ variable defined, it will default to the same C as before. +=head2 DATABASE CONFIG SWITCHING USING MULTIPLE CONFIG FILES + +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 +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. + +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: + + + + dsn dbi:SQLite:myapp.db + + + + +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-2008, Kennedy Clark, under Creative Commons License +Copyright 2006-2011, Kennedy Clark, under the +Creative Commons Attribution Share-Alike License Version 3.0 (L). -