| 1 |
NAME |
| 2 |
Test::WWW::Mechanize::Catalyst - Test::WWW::Mechanize for Catalyst |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
# We're in a t/*.t test script... |
| 6 |
use Test::WWW::Mechanize::Catalyst; |
| 7 |
|
| 8 |
# To test a Catalyst application named 'Catty': |
| 9 |
my $mech = Test::WWW::Mechanize::Catalyst->new(catalyst_app => 'Catty'); |
| 10 |
|
| 11 |
$mech->get_ok("/"); # no hostname needed |
| 12 |
is($mech->ct, "text/html"); |
| 13 |
$mech->title_is("Root", "On the root page"); |
| 14 |
$mech->content_contains("This is the root page", "Correct content"); |
| 15 |
$mech->follow_link_ok({text => 'Hello'}, "Click on Hello"); |
| 16 |
# ... and all other Test::WWW::Mechanize methods |
| 17 |
|
| 18 |
# White label site testing |
| 19 |
$mech->host("foo.com"); |
| 20 |
$mech->get_ok("/"); |
| 21 |
|
| 22 |
DESCRIPTION |
| 23 |
Catalyst is an elegant MVC Web Application Framework. |
| 24 |
Test::WWW::Mechanize is a subclass of WWW::Mechanize that incorporates |
| 25 |
features for web application testing. The Test::WWW::Mechanize::Catalyst |
| 26 |
module meshes the two to allow easy testing of Catalyst applications |
| 27 |
without needing to start up a web server. |
| 28 |
|
| 29 |
Testing web applications has always been a bit tricky, normally |
| 30 |
requiring starting a web server for your application and making real |
| 31 |
HTTP requests to it. This module allows you to test Catalyst web |
| 32 |
applications but does not require a server or issue HTTP requests. |
| 33 |
Instead, it passes the HTTP request object directly to Catalyst. Thus |
| 34 |
you do not need to use a real hostname: "http://localhost/" will do. |
| 35 |
However, this is optional. The following two lines of code do exactly |
| 36 |
the same thing: |
| 37 |
|
| 38 |
$mech->get_ok('/action'); |
| 39 |
$mech->get_ok('http://localhost/action'); |
| 40 |
|
| 41 |
Links which do not begin with / or are not for localhost can be handled |
| 42 |
as normal Web requests - this is handy if you have an external single |
| 43 |
sign-on system. You must set allow_external to true for this: |
| 44 |
|
| 45 |
$mech->allow_external(1); |
| 46 |
|
| 47 |
You can also test a remote server by setting the environment variable |
| 48 |
CATALYST_SERVER; for example: |
| 49 |
|
| 50 |
$ CATALYST_SERVER=http://example.com/myapp prove -l t |
| 51 |
|
| 52 |
will run the same tests on the application running at |
| 53 |
http://example.com/myapp regardless of whether or not you specify |
| 54 |
http:://localhost for Test::WWW::Mechanize::Catalyst. |
| 55 |
|
| 56 |
Furthermore, if you set CATALYST_SERVER, the server will be regarded as |
| 57 |
a remote server even if your links point to localhost. Thus, you can use |
| 58 |
Test::WWW::Mechanize::Catalyst to test your live webserver running on |
| 59 |
your local machine, if you need to test aspects of your deployment |
| 60 |
environment (for example, configuration options in an http.conf file) |
| 61 |
instead of just the Catalyst request handling. |
| 62 |
|
| 63 |
This makes testing fast and easy. Test::WWW::Mechanize provides |
| 64 |
functions for common web testing scenarios. For example: |
| 65 |
|
| 66 |
$mech->get_ok( $page ); |
| 67 |
$mech->title_is( "Invoice Status", "Make sure we're on the invoice page" ); |
| 68 |
$mech->content_contains( "Andy Lester", "My name somewhere" ); |
| 69 |
$mech->content_like( qr/(cpan|perl)\.org/, "Link to perl.org or CPAN" ); |
| 70 |
|
| 71 |
This module supports cookies automatically. |
| 72 |
|
| 73 |
To use this module you must pass it the name of the application. See the |
| 74 |
SYNOPSIS above. |
| 75 |
|
| 76 |
Note that Catalyst has a special development feature: the debug screen. |
| 77 |
By default this module will treat responses which are the debug screen |
| 78 |
as failures. If you actually want to test debug screens, please use: |
| 79 |
|
| 80 |
$mech->{catalyst_debug} = 1; |
| 81 |
|
| 82 |
An alternative to this module is Catalyst::Test. |
| 83 |
|
| 84 |
CONSTRUCTOR |
| 85 |
new |
| 86 |
Behaves like, and calls, WWW::Mechanize's "new" method. Any params |
| 87 |
passed in get passed to WWW::Mechanize's constructor. Note that we need |
| 88 |
to pass the name of the Catalyst application to the "use": |
| 89 |
|
| 90 |
use Test::WWW::Mechanize::Catalyst 'Catty'; |
| 91 |
my $mech = Test::WWW::Mechanize::Catalyst->new; |
| 92 |
|
| 93 |
METHODS |
| 94 |
allow_external |
| 95 |
Links which do not begin with / or are not for localhost can be handled |
| 96 |
as normal Web requests - this is handy if you have an external single |
| 97 |
sign-on system. You must set allow_external to true for this: |
| 98 |
|
| 99 |
$mech->allow_external(1); |
| 100 |
|
| 101 |
head2 catalyst_app |
| 102 |
|
| 103 |
The name of the Catalyst app which we are testing against. Read-only. |
| 104 |
|
| 105 |
host |
| 106 |
The host value to set the "Host:" HTTP header to, if none is present |
| 107 |
already in the request. If not set (default) then Catalyst::Test will |
| 108 |
set this to localhost:80 |
| 109 |
|
| 110 |
clear_host |
| 111 |
Unset the host attribute. |
| 112 |
|
| 113 |
has_host |
| 114 |
Do we have a value set for the host attribute |
| 115 |
|
| 116 |
$mech->get_ok($url, [ \%LWP_options ,] $desc) |
| 117 |
A wrapper around WWW::Mechanize's get(), with similar options, except |
| 118 |
the second argument needs to be a hash reference, not a hash. Returns |
| 119 |
true or false. |
| 120 |
|
| 121 |
$mech->title_is( $str [, $desc ] ) |
| 122 |
Tells if the title of the page is the given string. |
| 123 |
|
| 124 |
$mech->title_is( "Invoice Summary" ); |
| 125 |
|
| 126 |
$mech->title_like( $regex [, $desc ] ) |
| 127 |
Tells if the title of the page matches the given regex. |
| 128 |
|
| 129 |
$mech->title_like( qr/Invoices for (.+)/ |
| 130 |
|
| 131 |
$mech->title_unlike( $regex [, $desc ] ) |
| 132 |
Tells if the title of the page does NOT match the given regex. |
| 133 |
|
| 134 |
$mech->title_unlike( qr/Invoices for (.+)/ |
| 135 |
|
| 136 |
$mech->content_is( $str [, $desc ] ) |
| 137 |
Tells if the content of the page matches the given string. |
| 138 |
|
| 139 |
$mech->content_contains( $str [, $desc ] ) |
| 140 |
Tells if the content of the page contains *$str*. |
| 141 |
|
| 142 |
$mech->content_lacks( $str [, $desc ] ) |
| 143 |
Tells if the content of the page lacks *$str*. |
| 144 |
|
| 145 |
$mech->content_like( $regex [, $desc ] ) |
| 146 |
Tells if the content of the page matches *$regex*. |
| 147 |
|
| 148 |
$mech->content_unlike( $regex [, $desc ] ) |
| 149 |
Tells if the content of the page does NOT match *$regex*. |
| 150 |
|
| 151 |
$mech->page_links_ok( [ $desc ] ) |
| 152 |
Follow all links on the current page and test for HTTP status 200 |
| 153 |
|
| 154 |
$mech->page_links_ok('Check all links'); |
| 155 |
|
| 156 |
$mech->page_links_content_like( $regex,[ $desc ] ) |
| 157 |
Follow all links on the current page and test their contents for |
| 158 |
*$regex*. |
| 159 |
|
| 160 |
$mech->page_links_content_like( qr/foo/, |
| 161 |
'Check all links contain "foo"' ); |
| 162 |
|
| 163 |
$mech->page_links_content_unlike( $regex,[ $desc ] ) |
| 164 |
Follow all links on the current page and test their contents do not |
| 165 |
contain the specified regex. |
| 166 |
|
| 167 |
$mech->page_links_content_unlike(qr/Restricted/, |
| 168 |
'Check all links do not contain Restricted'); |
| 169 |
|
| 170 |
$mech->links_ok( $links [, $desc ] ) |
| 171 |
Check the current page for specified links and test for HTTP status 200. |
| 172 |
The links may be specified as a reference to an array containing |
| 173 |
WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name. |
| 174 |
|
| 175 |
my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ ); |
| 176 |
$mech->links_ok( \@links, 'Check all links for cnn.com' ); |
| 177 |
|
| 178 |
my @links = qw( index.html search.html about.html ); |
| 179 |
$mech->links_ok( \@links, 'Check main links' ); |
| 180 |
|
| 181 |
$mech->links_ok( 'index.html', 'Check link to index' ); |
| 182 |
|
| 183 |
$mech->link_status_is( $links, $status [, $desc ] ) |
| 184 |
Check the current page for specified links and test for HTTP status |
| 185 |
passed. The links may be specified as a reference to an array containing |
| 186 |
WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name. |
| 187 |
|
| 188 |
my @links = $mech->links(); |
| 189 |
$mech->link_status_is( \@links, 403, |
| 190 |
'Check all links are restricted' ); |
| 191 |
|
| 192 |
$mech->link_status_isnt( $links, $status [, $desc ] ) |
| 193 |
Check the current page for specified links and test for HTTP status |
| 194 |
passed. The links may be specified as a reference to an array containing |
| 195 |
WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name. |
| 196 |
|
| 197 |
my @links = $mech->links(); |
| 198 |
$mech->link_status_isnt( \@links, 404, |
| 199 |
'Check all links are not 404' ); |
| 200 |
|
| 201 |
$mech->link_content_like( $links, $regex [, $desc ] ) |
| 202 |
Check the current page for specified links and test the content of each |
| 203 |
against *$regex*. The links may be specified as a reference to an array |
| 204 |
containing WWW::Mechanize::Link objects, an array of URLs, or a scalar |
| 205 |
URL name. |
| 206 |
|
| 207 |
my @links = $mech->links(); |
| 208 |
$mech->link_content_like( \@links, qr/Restricted/, |
| 209 |
'Check all links are restricted' ); |
| 210 |
|
| 211 |
$mech->link_content_unlike( $links, $regex [, $desc ] ) |
| 212 |
Check the current page for specified links and test that the content of |
| 213 |
each does not match *$regex*. The links may be specified as a reference |
| 214 |
to an array containing WWW::Mechanize::Link objects, an array of URLs, |
| 215 |
or a scalar URL name. |
| 216 |
|
| 217 |
my @links = $mech->links(); |
| 218 |
$mech->link_content_like( \@links, qr/Restricted/, |
| 219 |
'Check all links are restricted' ); |
| 220 |
|
| 221 |
follow_link_ok( \%parms [, $comment] ) |
| 222 |
Makes a "follow_link()" call and executes tests on the results. The link |
| 223 |
must be found, and then followed successfully. Otherwise, this test |
| 224 |
fails. |
| 225 |
|
| 226 |
*%parms* is a hashref containing the params to pass to "follow_link()". |
| 227 |
Note that the params to "follow_link()" are a hash whereas the parms to |
| 228 |
this function are a hashref. You have to call this function like: |
| 229 |
|
| 230 |
$agent->follow_link_ok( {n=>3}, "looking for 3rd link" ); |
| 231 |
|
| 232 |
As with other test functions, $comment is optional. If it is supplied |
| 233 |
then it will display when running the test harness in verbose mode. |
| 234 |
|
| 235 |
Returns true value if the specified link was found and followed |
| 236 |
successfully. The HTTP::Response object returned by follow_link() is not |
| 237 |
available. |
| 238 |
|
| 239 |
CAVEATS |
| 240 |
External Redirects and allow_external |
| 241 |
If you use non-fully qualified urls in your test scripts (i.e. anything |
| 242 |
without a host, such as "->get_ok( "/foo")" ) and your app redirects to |
| 243 |
an external URL, expect to be bitten once you come back to your |
| 244 |
application's urls (it will try to request them on the remote server). |
| 245 |
This is due to a limitation in WWW::Mechanize. |
| 246 |
|
| 247 |
One workaround for this is that if you are expecting to redirect to an |
| 248 |
external site, clone the TWMC object and use the cloned object for the |
| 249 |
external redirect. |
| 250 |
|
| 251 |
SEE ALSO |
| 252 |
Related modules which may be of interest: Catalyst, |
| 253 |
Test::WWW::Mechanize, WWW::Mechanize. |
| 254 |
|
| 255 |
AUTHOR |
| 256 |
Ash Berlin "<[email protected]>" (current maintainer) |
| 257 |
|
| 258 |
Original Author: Leon Brocard, "<[email protected]>" |
| 259 |
|
| 260 |
COPYRIGHT |
| 261 |
Copyright (C) 2005-9, Leon Brocard |
| 262 |
|
| 263 |
LICENSE |
| 264 |
This module is free software; you can redistribute it or modify it under |
| 265 |
the same terms as Perl itself. |
| 266 |
|