1Mechanize(3) User Contributed Perl Documentation Mechanize(3)
2
6 Test::WWW::Mechanize - Testing-specific WWW::Mechanize subclass
7
9 Version 1.28
10
12 Test::WWW::Mechanize is a subclass of WWW::Mechanize that incorporates
13 features for web application testing. For example:
14 use Test::More tests => 5;
16 use Test::WWW::Mechanize;
17 my $mech = Test::WWW::Mechanize->new;
19 $mech->get_ok( $page );
20 $mech->base_is( 'http://petdance.com/', 'Proper <BASE HREF>' );
21 $mech->title_is( "Invoice Status", "Make sure we're on the invoice page" );
22 $mech->content_contains( "Andy Lester", "My name somewhere" );
23 $mech->content_like( qr/(cpan|perl)\.org/, "Link to perl.org or CPAN" );
24 This is equivalent to:
26 use Test::More tests => 5;
28 use WWW::Mechanize;
29 my $mech = WWW::Mechanize->new;
31 $mech->get( $page );
32 ok( $mech->success );
33 is( $mech->base, 'http://petdance.com', 'Proper <BASE HREF>' );
34 is( $mech->title, "Invoice Status", "Make sure we're on the invoice page" );
35 ok( index( $mech->content, "Andy Lester" ) >= 0, "My name somewhere" );
36 like( $mech->content, qr/(cpan|perl)\.org/, "Link to perl.org or CPAN" );
37 but has nicer diagnostics if they fail.
39 Default descriptions will be supplied for most methods if you omit
41 them. e.g.
42 my $mech = Test::WWW::Mechanize->new;
44 $mech->get_ok( 'http://petdance.com/' );
45 $mech->base_is( 'http://petdance.com/' );
46 $mech->title_is( "Invoice Status" );
47 $mech->content_contains( "Andy Lester" );
48 $mech->content_like( qr/(cpan|perl)\.org/ );
49 results in
51 ok - Got 'http://petdance.com/' ok
53 ok - Base is 'http://petdance.com/'
54 ok - Title is 'Invoice Status'
55 ok - Content contains 'Andy Lester'
56 ok - Content is like '(?-xism:(cpan|perl)\.org)'
57
59 new( %args )
60 Behaves like, and calls, WWW::Mechanize's "new" method. Any parms
61 passed in get passed to WWW::Mechanize's constructor.
62 You can pass in "autolint => 1" to make Test::WWW::Mechanize
64 automatically run HTML::Lint after any of the following methods are
65 called.
66 · get_ok()
68 and will eventually do the same after any of the following:
70 · post_ok()
72 · back_ok()
74 · submit_form_ok()
76 · follow_link_ok()
78 · click_ok()
80 This means you no longerhave to do the following:
82 my $mech = Test::WWW::Mechanize->new();
84 $mech->get_ok( $url, 'Fetch the intro page' );
85 $mech->html_lint_ok( 'Intro page looks OK' );
86 and can simply do
88 my $mech = Test::WWW::Mechanize->new( autolint => 1 );
90 $mech->get_ok( $url, 'Fetch the intro page' );
91 The "$mech->get_ok()" only counts as one test in the test count. Both
93 the main IO operation and the linting must pass for the entire test to
94 pass.
95
97 $mech->get_ok($url, [ \%LWP_options ,] $desc)
98 A wrapper around WWW::Mechanize's get(), with similar options, except
99 the second argument needs to be a hash reference, not a hash. Like
100 well-behaved "*_ok()" functions, it returns true if the test passed, or
101 false if not.
102 A default description of "GET $url" is used if none if provided.
104 $mech->head_ok($url, [ \%LWP_options ,] $desc)
106 A wrapper around WWW::Mechanize's head(), with similar options, except
107 the second argument needs to be a hash reference, not a hash. Like
108 well-behaved "*_ok()" functions, it returns true if the test passed, or
109 false if not.
110 A default description of "HEAD $url" is used if none if provided.
112 $mech->post_ok( $url, [ \%LWP_options ,] $desc )
114 A wrapper around WWW::Mechanize's post(), with similar options, except
115 the second argument needs to be a hash reference, not a hash. Like
116 well-behaved "*_ok()" functions, it returns true if the test passed, or
117 false if not.
118 A default description of "POST to $url" is used if none if provided.
120 $mech->put_ok( $url, [ \%LWP_options ,] $desc )
122 A wrapper around WWW::Mechanize's put(), with similar options, except
123 the second argument needs to be a hash reference, not a hash. Like
124 well-behaved "*_ok()" functions, it returns true if the test passed, or
125 false if not.
126 A default description of "PUT to $url" is used if none if provided.
128 $mech->submit_form_ok( \%parms [, $desc] )
130 Makes a "submit_form()" call and executes tests on the results. The
131 form must be found, and then submitted successfully. Otherwise, this
132 test fails.
133 %parms is a hashref containing the parms to pass to "submit_form()".
135 Note that the parms to "submit_form()" are a hash whereas the parms to
136 this function are a hashref. You have to call this function like:
137 $agent->submit_form_ok( {n=>3}, "looking for 3rd link" );
139 As with other test functions, $desc is optional. If it is supplied
141 then it will display when running the test harness in verbose mode.
142 Returns true value if the specified link was found and followed
144 successfully. The HTTP::Response object returned by submit_form() is
145 not available.
146 $mech->follow_link_ok( \%parms [, $desc] )
148 Makes a "follow_link()" call and executes tests on the results. The
149 link must be found, and then followed successfully. Otherwise, this
150 test fails.
151 %parms is a hashref containing the parms to pass to "follow_link()".
153 Note that the parms to "follow_link()" are a hash whereas the parms to
154 this function are a hashref. You have to call this function like:
155 $mech->follow_link_ok( {n=>3}, "looking for 3rd link" );
157 As with other test functions, $desc is optional. If it is supplied
159 then it will display when running the test harness in verbose mode.
160 Returns a true value if the specified link was found and followed
162 successfully. The HTTP::Response object returned by follow_link() is
163 not available.
164 click_ok( $button[, $desc] )
166 Clicks the button named by $button. An optional $desc can be given for
167 the test.
168
170 $mech->html_lint_ok( [$desc] )
171 Checks the validity of the HTML on the current page. If the page is
172 not HTML, then it fails. The URI is automatically appended to the
173 $desc.
174 Note that HTML::Lint must be installed for this to work. Otherwise, it
176 will blow up.
177 $mech->title_is( $str [, $desc ] )
179 Tells if the title of the page is the given string.
180 $mech->title_is( "Invoice Summary" );
182 $mech->title_like( $regex [, $desc ] )
184 Tells if the title of the page matches the given regex.
185 $mech->title_like( qr/Invoices for (.+)/
187 $mech->title_unlike( $regex [, $desc ] )
189 Tells if the title of the page matches the given regex.
190 $mech->title_unlike( qr/Invoices for (.+)/
192 $mech->base_is( $str [, $desc ] )
194 Tells if the base of the page is the given string.
195 $mech->base_is( "http://example.com/" );
197 $mech->base_like( $regex [, $desc ] )
199 Tells if the base of the page matches the given regex.
200 $mech->base_like( qr{http://example.com/index.php?PHPSESSID=(.+)});
202 $mech->base_unlike( $regex [, $desc ] )
204 Tells if the base of the page matches the given regex.
205 $mech->base_unlike( qr{http://example.com/index.php?PHPSESSID=(.+)});
207 $mech->content_is( $str [, $desc ] )
209 Tells if the content of the page matches the given string
210 $mech->content_contains( $str [, $desc ] )
212 Tells if the content of the page contains $str.
213 $mech->content_lacks( $str [, $desc ] )
215 Tells if the content of the page lacks $str.
216 $mech->content_like( $regex [, $desc ] )
218 Tells if the content of the page matches $regex.
219 $mech->content_unlike( $regex [, $desc ] )
221 Tells if the content of the page does NOT match $regex.
222 $mech->has_tag( $tag, $text [, $desc ] )
224 Tells if the page has a $tag tag with the given content in its text.
225 $mech->has_tag_like( $tag, $regex [, $desc ] )
227 Tells if the page has a $tag tag with the given content in its text.
228 $mech->followable_links()
230 Returns a list of links that Mech can follow. This is only http and
231 https links.
232 $mech->page_links_ok( [ $desc ] )
234 Follow all links on the current page and test for HTTP status 200
235 $mech->page_links_ok('Check all links');
237 $mech->page_links_content_like( $regex [, $desc ] )
239 Follow all links on the current page and test their contents for
240 $regex.
241 $mech->page_links_content_like( qr/foo/,
243 'Check all links contain "foo"' );
244 $mech->page_links_content_unlike( $regex [, $desc ] )
246 Follow all links on the current page and test their contents do not
247 contain the specified regex.
248 $mech->page_links_content_unlike(qr/Restricted/,
250 'Check all links do not contain Restricted');
251 $mech->links_ok( $links [, $desc ] )
253 Follow specified links on the current page and test for HTTP status
254 200. The links may be specified as a reference to an array containing
255 WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name.
256 my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ );
258 $mech->links_ok( \@links, 'Check all links for cnn.com' );
259 my @links = qw( index.html search.html about.html );
261 $mech->links_ok( \@links, 'Check main links' );
262 $mech->links_ok( 'index.html', 'Check link to index' );
264 $mech->link_status_is( $links, $status [, $desc ] )
266 Follow specified links on the current page and test for HTTP status
267 passed. The links may be specified as a reference to an array
268 containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
269 URL name.
270 my @links = $mech->followable_links();
272 $mech->link_status_is( \@links, 403,
273 'Check all links are restricted' );
274 $mech->link_status_isnt( $links, $status [, $desc ] )
276 Follow specified links on the current page and test for HTTP status
277 passed. The links may be specified as a reference to an array
278 containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
279 URL name.
280 my @links = $mech->followable_links();
282 $mech->link_status_isnt( \@links, 404,
283 'Check all links are not 404' );
284 $mech->link_content_like( $links, $regex [, $desc ] )
286 Follow specified links on the current page and test the resulting
287 content of each against $regex. The links may be specified as a
288 reference to an array containing WWW::Mechanize::Link objects, an array
289 of URLs, or a scalar URL name.
290 my @links = $mech->followable_links();
292 $mech->link_content_like( \@links, qr/Restricted/,
293 'Check all links are restricted' );
294 $mech->link_content_unlike( $links, $regex [, $desc ] )
296 Follow specified links on the current page and test that the resulting
297 content of each does not match $regex. The links may be specified as a
298 reference to an array containing WWW::Mechanize::Link objects, an array
299 of URLs, or a scalar URL name.
300 my @links = $mech->followable_links();
302 $mech->link_content_unlike( \@links, qr/Restricted/,
303 'No restricted links' );
304 $mech->stuff_inputs( [\%options] )
306 Finds all free-text input fields (text, textarea, and password) in the
307 current form and fills them to their maximum length in hopes of finding
308 application code that can't handle it. Fields with no maximum length
309 and all textarea fields are set to 66000 bytes, which will often be
310 enough to overflow the data's eventual recepticle.
311 There is no return value.
313 If there is no current form then nothing is done.
315 The hashref $options can contain the following keys:
317 · ignore
319 hash value is arrayref of field names to not touch, e.g.:
321 $mech->stuff_inputs( {
323 ignore => [qw( specialfield1 specialfield2 )],
324 } );
325 · fill
327 hash value is default string to use when stuffing fields. Copies
329 of the string are repeated up to the max length of each field.
330 E.g.:
331 $mech->stuff_inputs( {
333 fill => '@' # stuff all fields with something easy to recognize
334 } );
335 · specs
337 hash value is arrayref of hashrefs with which you can pass detailed
339 instructions about how to stuff a given field. E.g.:
340 $mech->stuff_inputs( {
342 specs=>{
343 # Some fields are datatype-constrained. It's most common to
344 # want the field stuffed with valid data.
345 widget_quantity => { fill=>'9' },
346 notes => { maxlength=>2000 },
347 }
348 } );
349 The specs allowed are fill (use this fill for the field rather than
351 the default) and maxlength (use this as the field's maxlength
352 instead of any maxlength specified in the HTML).
353
355 Add HTML::Tidy capabilities.
356 Add a broken image check.
358
360 Andy Lester, "<andy at petdance.com>"
361
363 Please report any bugs or feature requests to
364 <http://code.google.com/p/www-mechanize/issues/list>. I will be
365 notified, and then you'll automatically be notified of progress on your
366 bug as I make changes.
367
369 You can find documentation for this module with the perldoc command.
370 perldoc Test::WWW::Mechanize
372 You can also look for information at:
374 · Google Code bug tracker
376 http://code.google.com/p/www-mechanize/issues/list
378 <http://code.google.com/p/www-mechanize/issues/list>
379 Please do not use the old queues for WWW::Mechanize and
381 Test::WWW::Mechanize at
382 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-WWW-Mechanize
383 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-WWW-Mechanize>
384 · AnnoCPAN: Annotated CPAN documentation
386 http://annocpan.org/dist/Test-WWW-Mechanize
388 <http://annocpan.org/dist/Test-WWW-Mechanize>
389 · CPAN Ratings
391 http://cpanratings.perl.org/d/Test-WWW-Mechanize
393 <http://cpanratings.perl.org/d/Test-WWW-Mechanize>
394 · Search CPAN
396 http://search.cpan.org/dist/Test-WWW-Mechanize
398 <http://search.cpan.org/dist/Test-WWW-Mechanize>
399
401 Thanks to Niko Tyni, Greg Sheard, Michael Schwern, Mark Blackman, Mike
402 O'Regan, Shawn Sorichetti, Chris Dolan, Matt Trout, MATSUNO Tokuhiro,
403 and Pete Krawczyk for patches.
404
406 Copyright 2004-2010 Andy Lester.
407 This program is free software; you can redistribute it and/or modify it
409 under the terms of either:
410 · the GNU General Public License as published by the Free Software
412 Foundation; either version 1, or (at your option) any later
413 version, or
414 · the Artistic License version 2.0.
416perl v5.12.0 2010-04-13 Mechanize(3)