Bug #40565 for Test-WWW-Mechanize-Catalyst: Doc patch about running TWMC against "remote" servers on localhost

The docs for TWMC talk about the convenience of _not_ running a live server, but that you can test something against a remote server if necessary. However, the need to test against a live server, but locally, is a real one, in case you need to test an app against a production environment. This patch clears this up (though may be wrong, depending on how TWMC actually handles this), and fixes some other minor problems as well.

--- /usr/share/perl5/Test/WWW/Mechanize/Catalyst.pm 2008-04-29 15:25:55.000000000 -0400 +++ Catalyst.pm 2008-10-10 12:12:18.000000000 -0400 @@ -135,12 +135,12 @@ Framework. L<Test::WWW::Mechanize> is a subclass of L<WWW::Mechanize> that incorporates features for web application testing. The L<Test::WWW::Mechanize::Catalyst> module meshes the two to allow easy -testing of L<Catalyst> applications without starting up a web server. +testing of L<Catalyst> applications. Testing web applications has always been a bit tricky, normally -starting a web server for your application and making real HTTP +requiring starting a web server for your application and making real HTTP requests to it. This module allows you to test L<Catalyst> web -applications but does not start a server or issue HTTP +applications but does not require a live server or the issuing of HTTP requests. Instead, it passes the HTTP request object directly to L<Catalyst>. Thus you do not need to use a real hostname: "http://localhost/" will do. However, this is optional. The following @@ -153,16 +153,23 @@ as normal Web requests - this is handy if you have an external single sign-on system. You must set allow_external to true for this: - $m->allow_external(1); + $mech->allow_external(1); You can also test a remote server by setting the environment variable -CATALYST_SERVER, for example: +CATALYST_SERVER; for example $ CATALYST_SERVER=http://example.com/myapp prove -l t will run the same tests on the application running at http://example.com/myapp regardless of whether or not you specify -http:://localhost for Test::WWW::Mechanize::Catalyst. +http:://localhost for Test::WWW::Mechanize::Catalyst. + +Furthermore, if you set CATALYST_SERVER, the server will be regarded +as a remote server even if your links point to localhost. Thus, you +can use Test::WWW::Mechanize::Catalyst to test your live webserver +running on your local machine, if you need to test aspects of your +deployment environment (for example, configuration options in an +http.conf file) instead of a Perl HTTP object. This makes testing fast and easy. L<Test::WWW::Mechanize> provides functions for common web testing scenarios. For example: @@ -182,7 +189,7 @@ debug screen as failures. If you actually want to test debug screens, please use: - $m->{catalyst_debug} = 1; + $mech->{catalyst_debug} = 1; An alternative to this module is L<Catalyst::Test>. @@ -190,7 +197,7 @@ =head2 new -Behaves like, and calls, L<WWW::Mechanize>'s C<new> method. Any parms +Behaves like, and calls, L<WWW::Mechanize>'s C<new> method. Any params passed in get passed to WWW::Mechanize's constructor. Note that we need to pass the name of the Catalyst application to the "use": @@ -227,13 +234,13 @@ =head2 $mech->title_unlike( $regex [, $desc ] ) -Tells if the title of the page matches the given regex. +Tells if the title of the page does NOT match the given regex. $mech->title_unlike( qr/Invoices for (.+)/ =head2 $mech->content_is( $str [, $desc ] ) -Tells if the content of the page matches the given string +Tells if the content of the page matches the given string. =head2 $mech->content_contains( $str [, $desc ] ) @@ -266,7 +273,7 @@ =head2 $mech->page_links_content_unlike( $regex,[ $desc ] ) -Follow all links on the current page and test their contents do not +Follow all links on the current page and test that their contents do NOT contain the specified regex. $mech->page_links_content_unlike(qr/Restricted/, @@ -322,8 +329,8 @@ =head2 $mech->link_content_unlike( $links, $regex [, $desc ] ) -Check the current page for specified links and test the content of each -does not match I<$regex>. The links may be specified as a reference to +Check the current page for specified links and test that the content of each +does NOT match I<$regex>. The links may be specified as a reference to an array containing L<WWW::Mechanize::Link> objects, an array of URLs, or a scalar URL name. @@ -337,8 +344,8 @@ The link must be found, and then followed successfully. Otherwise, this test fails. -I<%parms> is a hashref containing the parms to pass to C<follow_link()>. -Note that the parms to C<follow_link()> are a hash whereas the parms to +I<%parms> is a hashref containing the params to pass to C<follow_link()>. +Note that the params to C<follow_link()> are a hash whereas the params to this function are a hashref. You have to call this function like: $agent->follow_like_ok( {n=>3}, "looking for 3rd link" ); @@ -352,7 +359,7 @@ =head1 SEE ALSO -Related modules which may be of interest: L<Catalyst>, +Related modules that may be of interest: L<Catalyst>, L<Test::WWW::Mechanize>, L<WWW::Mechanize>. =head1 AUTHOR