1Mechanize(3) User Contributed Perl Documentation Mechanize(3)
2
6 Test::WWW::Mechanize - Testing-specific WWW::Mechanize subclass
7
9 Version 1.60
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->text_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( format => 'text' ), '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 - Text 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. You can also pass in an HTML::Lint object like this:
66 my $lint = HTML::Lint->new( only_types => HTML::Lint::Error::STRUCTURE );
68 my $mech = Test::WWW::Mechanize->new( autolint => $lint );
69 The same is also possible with "autotidy => 1" to use HTML::Tidy5.
71 • get_ok()
73 • post_ok()
75 • submit_form_ok()
77 • follow_link_ok()
79 • click_ok()
81 This means you no longer have to do the following:
83 my $mech = Test::WWW::Mechanize->new();
85 $mech->get_ok( $url, 'Fetch the intro page' );
86 $mech->html_lint_ok( 'Intro page looks OK' );
87 and can simply do
89 my $mech = Test::WWW::Mechanize->new( autolint => 1 );
91 $mech->get_ok( $url, 'Fetch the intro page' );
92 The "$mech->get_ok()" only counts as one test in the test count. Both
94 the main IO operation and the linting must pass for the entire test to
95 pass.
96 You can control autolint and autotidy on the fly with the "autolint"
98 and "autotidy" methods.
99
101 $mech->get_ok($url, [ \%LWP_options ,] $desc)
102 A wrapper around WWW::Mechanize's get(), with similar options, except
103 the second argument needs to be a hash reference, not a hash. Like
104 well-behaved *_ok() functions, it returns true if the test passed, or
105 false if not.
106 A default description of "GET $url" is used if none if provided.
108 $mech->head_ok($url, [ \%LWP_options ,] $desc)
110 A wrapper around WWW::Mechanize's head(), with similar options, except
111 the second argument needs to be a hash reference, not a hash. Like
112 well-behaved *_ok() functions, it returns true if the test passed, or
113 false if not.
114 A default description of "HEAD $url" is used if none if provided.
116 $mech->post_ok( $url, [ \%LWP_options ,] $desc )
118 A wrapper around WWW::Mechanize's post(), with similar options, except
119 the second argument needs to be a hash reference, not a hash. Like
120 well-behaved *_ok() functions, it returns true if the test passed, or
121 false if not.
122 NOTE Due to compatibility reasons it is not possible to pass additional
124 LWP_options beyond form data via this method (such as Content or
125 Content-Type). It is recommend that you use WWW::Mechanize's post()
126 directly for instances where more granular control of the post is
127 needed.
128 A default description of "POST to $url" is used if none if provided.
130 $mech->put_ok( $url, [ \%LWP_options ,] $desc )
132 A wrapper around WWW::Mechanize's put(), with similar options, except
133 the second argument needs to be a hash reference, not a hash. Like
134 well-behaved *_ok() functions, it returns true if the test passed, or
135 false if not.
136 A default description of "PUT to $url" is used if none if provided.
138 $mech->delete_ok( $url, [ \%LWP_options ,] $desc )
140 A wrapper around WWW::Mechanize's delete(), with similar options,
141 except the second argument needs to be a hash reference, not a hash.
142 Like well-behaved *_ok() functions, it returns true if the test passed,
143 or false if not.
144 A default description of "DELETE to $url" is used if none if provided.
146 $mech->submit_form_ok( \%parms [, $desc] )
148 Makes a submit_form() call and executes tests on the results. The form
149 must be found, and then submitted successfully. Otherwise, this test
150 fails.
151 %parms is a hashref containing the parms to pass to submit_form().
153 Note that the parms to submit_form() are a hash whereas the parms to
154 this function are a hashref. You have to call this function like:
155 $mech->submit_form_ok( {
157 form_number => 3,
158 fields => {
159 answer => 42
160 },
161 }, 'now we just need the question'
162 );
163 As with other test functions, $desc is optional. If it is supplied
165 then it will display when running the test harness in verbose mode.
166 Returns true value if the specified link was found and followed
168 successfully. The HTTP::Response object returned by submit_form() is
169 not available.
170 $mech->follow_link_ok( \%parms [, $desc] )
172 Makes a follow_link() call and executes tests on the results. The link
173 must be found, and then followed successfully. Otherwise, this test
174 fails.
175 %parms is a hashref containing the parms to pass to follow_link().
177 Note that the parms to follow_link() are a hash whereas the parms to
178 this function are a hashref. You have to call this function like:
179 $mech->follow_link_ok( {n=>3}, 'looking for 3rd link' );
181 As with other test functions, $desc is optional. If it is supplied
183 then it will display when running the test harness in verbose mode.
184 Returns a true value if the specified link was found and followed
186 successfully. The HTTP::Response object returned by follow_link() is
187 not available.
188 $mech->click_ok( $button[, $desc] )
190 $mech->click_ok( \@button-and-coordinates [, $desc ] )
191 Clicks the button named by $button. An optional $desc can be given for
192 the test.
193 $mech->click_ok( 'continue', 'Clicking the "Continue" button' );
195 Alternatively the first argument can be an arrayref with three
197 elements: The name of the button and the X and Y coordinates of the
198 button.
199 $mech->click_ok( [ 'continue', 12, 47 ], 'Clicking the "Continue" button' );
201
203 $mech->header_exists_ok( $header [, $desc ] )
204 Assures that a given response header exists. The actual value of the
205 response header is not checked, only that the header exists.
206 $mech->lacks_header_ok( $header [, $desc ] )
208 Assures that a given response header does NOT exist.
209 $mech->header_is( $header, $value [, $desc ] )
211 Assures that a given response header exists and has the given value.
212 $mech->header_like( $header, $value [, $desc ] )
214 Assures that a given response header exists and has the given value.
215
217 $mech->html_lint_ok( [$desc] )
218 Checks the validity of the HTML on the current page using the
219 HTML::Lint module. If the page is not HTML, then it fails. The URI is
220 automatically appended to the $desc.
221 Note that HTML::Lint must be installed for this to work. Otherwise, it
223 will blow up.
224 $mech->html_tidy_ok( [$desc] )
226 Checks the validity of the HTML on the current page using the
227 HTML::Tidy module. If the page is not HTML, then it fails. The URI is
228 automatically appended to the $desc.
229 Note that HTML::tidy must be installed for this to work. Otherwise, it
231 will blow up.
232 $mech->content_for_tidy()
234 This method is called by html_tidy_ok() to get the content that should
235 be validated by HTML::Tidy5. By default, this is just content(), but
236 subclasses can override it to modify the content before validation.
237 This method should not change any state in the Mech object.
239 Specifically, it should not actually modify any of the actual content.
240 $mech->title_is( $str [, $desc ] )
242 Tells if the title of the page is the given string.
243 $mech->title_is( 'Invoice Summary' );
245 $mech->title_like( $regex [, $desc ] )
247 Tells if the title of the page matches the given regex.
248 $mech->title_like( qr/Invoices for (.+)/ );
250 $mech->title_unlike( $regex [, $desc ] )
252 Tells if the title of the page matches the given regex.
253 $mech->title_unlike( qr/Invoices for (.+)/ );
255 $mech->base_is( $str [, $desc ] )
257 Tells if the base of the page is the given string.
258 $mech->base_is( 'http://example.com/' );
260 $mech->base_like( $regex [, $desc ] )
262 Tells if the base of the page matches the given regex.
263 $mech->base_like( qr{http://example.com/index.php?PHPSESSID=(.+)});
265 $mech->base_unlike( $regex [, $desc ] )
267 Tells if the base of the page matches the given regex.
268 $mech->base_unlike( qr{http://example.com/index.php?PHPSESSID=(.+)});
270 $mech->content_is( $str [, $desc ] )
272 Tells if the content of the page matches the given string
273 $mech->content_contains( $str [, $desc ] )
275 Tells if the content of the page contains $str.
276 $mech->content_lacks( $str [, $desc ] )
278 Tells if the content of the page lacks $str.
279 $mech->content_like( $regex [, $desc ] )
281 Tells if the content of the page matches $regex.
282 $mech->content_unlike( $regex [, $desc ] )
284 Tells if the content of the page does NOT match $regex.
285 $mech->text_contains( $str [, $desc ] )
287 Tells if the text form of the page's content contains $str.
288 When your page contains HTML which is difficult, unimportant, or
290 unlikely to match over time as designers alter markup, use
291 "text_contains" instead of "content_contains".
292 # <b>Hi, <i><a href="some/path">User</a></i>!</b>
294 $mech->content_contains('Hi, User'); # Fails.
295 $mech->text_contains('Hi, User'); # Passes.
296 Text is determined by calling "$mech->text()". See "content" in
298 WWW::Mechanize.
299 $mech->text_lacks( $str [, $desc ] )
301 Tells if the text of the page lacks $str.
302 $mech->text_like( $regex [, $desc ] )
304 Tells if the text form of the page's content matches $regex.
305 $mech->text_unlike( $regex [, $desc ] )
307 Tells if the text format of the page's content does NOT match $regex.
308 $mech->has_tag( $tag, $text [, $desc ] )
310 Tells if the page has a $tag tag with the given content in its text.
311 $mech->has_tag_like( $tag, $regex [, $desc ] )
313 Tells if the page has a $tag tag with the given content in its text.
314 $mech->page_links_ok( [ $desc ] )
316 Follow all links on the current page and test for HTTP status 200
317 $mech->page_links_ok('Check all links');
319 $mech->page_links_content_like( $regex [, $desc ] )
321 Follow all links on the current page and test their contents for
322 $regex.
323 $mech->page_links_content_like( qr/foo/,
325 'Check all links contain "foo"' );
326 $mech->page_links_content_unlike( $regex [, $desc ] )
328 Follow all links on the current page and test their contents do not
329 contain the specified regex.
330 $mech->page_links_content_unlike(qr/Restricted/,
332 'Check all links do not contain Restricted');
333 $mech->links_ok( $links [, $desc ] )
335 Follow specified links on the current page and test for HTTP status
336 200. The links may be specified as a reference to an array containing
337 WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name.
338 my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ );
340 $mech->links_ok( \@links, 'Check all links for cnn.com' );
341 my @links = qw( index.html search.html about.html );
343 $mech->links_ok( \@links, 'Check main links' );
344 $mech->links_ok( 'index.html', 'Check link to index' );
346 $mech->link_status_is( $links, $status [, $desc ] )
348 Follow specified links on the current page and test for HTTP status
349 passed. The links may be specified as a reference to an array
350 containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
351 URL name.
352 my @links = $mech->followable_links();
354 $mech->link_status_is( \@links, 403,
355 'Check all links are restricted' );
356 $mech->link_status_isnt( $links, $status [, $desc ] )
358 Follow specified links on the current page and test for HTTP status
359 passed. The links may be specified as a reference to an array
360 containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
361 URL name.
362 my @links = $mech->followable_links();
364 $mech->link_status_isnt( \@links, 404,
365 'Check all links are not 404' );
366 $mech->link_content_like( $links, $regex [, $desc ] )
368 Follow specified links on the current page and test the resulting
369 content of each against $regex. The links may be specified as a
370 reference to an array containing WWW::Mechanize::Link objects, an array
371 of URLs, or a scalar URL name.
372 my @links = $mech->followable_links();
374 $mech->link_content_like( \@links, qr/Restricted/,
375 'Check all links are restricted' );
376 $mech->link_content_unlike( $links, $regex [, $desc ] )
378 Follow specified links on the current page and test that the resulting
379 content of each does not match $regex. The links may be specified as a
380 reference to an array containing WWW::Mechanize::Link objects, an array
381 of URLs, or a scalar URL name.
382 my @links = $mech->followable_links();
384 $mech->link_content_unlike( \@links, qr/Restricted/,
385 'No restricted links' );
386
388 $mech->scrape_text_by_attr( $attr, $attr_value [, $html ] )
389 $mech->scrape_text_by_attr( $attr, $attr_regex [, $html ] )
390 Returns a list of strings, each string the text surrounded by an
391 element with attribute $attr of value $value. You can also pass in a
392 regular expression. If nothing is found the return is an empty list.
393 In scalar context the return is the first string found.
394 If passed, $html is scraped instead of the current page's content.
396 $mech->scrape_text_by_id( $id [, $html ] )
398 Finds all elements with the given ID attribute and pulls out the text
399 that that element encloses.
400 In list context, returns a list of all strings found. In scalar
402 context, returns the first one found.
403 If $html is not provided then the current content is used.
405 $mech->scraped_id_is( $id, $expected [, $msg] )
407 Scrapes the current page for given ID and tests that it matches the
408 expected value.
409 $mech->scraped_id_like( $id, $expected_regex [, $msg] )
411 Scrapes the current page for given id and tests that it matches the
412 expected regex.
413 $mech->id_exists( $id )
415 Returns TRUE/FALSE if the given ID exists in the given HTML, or if none
416 is provided, then the current page.
417 The Mech object caches the IDs so that it doesn't bother reparsing
419 every time it's asked about an ID.
420 $agent->id_exists_ok( $id [, $msg] )
422 Verifies there is an HTML element with ID $id in the page.
423 $agent->ids_exist_ok( \@ids [, $msg] )
425 Verifies an HTML element exists with each ID in "\@ids".
426 $agent->lacks_id_ok( $id [, $msg] )
428 Verifies there is NOT an HTML element with ID $id in the page.
429 $agent->lacks_ids_ok( \@ids [, $msg] )
431 Verifies there are no HTML elements with any of the ids given in
432 "\@ids".
433 $mech->button_exists( $button )
435 Returns a boolean saying whether a submit button with the name $button
436 exists. Does not do a test. For that you want "button_exists_ok" or
437 "lacks_button_ok".
438 $mech->button_exists_ok( $button [, $msg] )
440 Asserts that the button exists on the page.
441 $mech->lacks_button_ok( $button [, $msg] )
443 Asserts that no button named $button exists on the page.
444
446 $mech->autolint( [$status] )
447 Without an argument, this method returns a true or false value
448 indicating whether autolint is active.
449 When passed an argument, autolint is turned on or off depending on
451 whether the argument is true or false, and the previous autolint status
452 is returned. As with the autolint option of "new", $status can be an
453 HTML::Lint object.
454 If autolint is currently using an HTML::Lint object you provided, the
456 return is that object, so you can change and exactly restore autolint
457 status:
458 my $old_status = $mech->autolint( 0 );
460 ... operations that should not be linted ...
461 $mech->autolint( $old_status );
462 $mech->autotidy( [$status] )
464 Without an argument, this method returns a true or false value
465 indicating whether autotidy is active.
466 When passed an argument, autotidy is turned on or off depending on
468 whether the argument is true or false, and the previous autotidy status
469 is returned. As with the autotidy option of "new", $status can be an
470 HTML::Tidy5 object.
471 If autotidy is currently using an HTML::Tidy5 object you provided, the
473 return is that object, so you can change and exactly restore autotidy
474 status:
475 my $old_status = $mech->autotidy( 0 );
477 ... operations that should not be tidied ...
478 $mech->autotidy( $old_status );
479 $mech->grep_inputs( \%properties )
481 Returns a list of all the input controls in the current form whose
482 properties match all of the regexes in $properties. The controls
483 returned are all descended from HTML::Form::Input.
484 If $properties is undef or empty then all inputs will be returned.
486 If there is no current page, there is no form on the current page, or
488 there are no submit controls in the current form then the return will
489 be an empty list.
490 # Get all text controls whose names begin with "customer".
492 my @customer_text_inputs =
493 $mech->grep_inputs( {
494 type => qr/^(text|textarea)$/,
495 name => qr/^customer/
496 }
497 );
498 $mech->grep_submits( \%properties )
500 grep_submits() does the same thing as grep_inputs() except that it only
501 returns controls that are submit controls, ignoring other types of
502 input controls like text and checkboxes.
503 $mech->stuff_inputs( [\%options] )
505 Finds all free-text input fields (text, textarea, and password) in the
506 current form and fills them to their maximum length in hopes of finding
507 application code that can't handle it. Fields with no maximum length
508 and all textarea fields are set to 66000 bytes, which will often be
509 enough to overflow the data's eventual receptacle.
510 There is no return value.
512 If there is no current form then nothing is done.
514 The hashref $options can contain the following keys:
516 • ignore
518 hash value is arrayref of field names to not touch, e.g.:
520 $mech->stuff_inputs( {
522 ignore => [qw( specialfield1 specialfield2 )],
523 } );
524 • fill
526 hash value is default string to use when stuffing fields. Copies
528 of the string are repeated up to the max length of each field.
529 E.g.:
530 $mech->stuff_inputs( {
532 fill => '@' # stuff all fields with something easy to recognize
533 } );
534 • specs
536 hash value is arrayref of hashrefs with which you can pass detailed
538 instructions about how to stuff a given field. E.g.:
539 $mech->stuff_inputs( {
541 specs=>{
542 # Some fields are datatype-constrained. It's most common to
543 # want the field stuffed with valid data.
544 widget_quantity => { fill=>'9' },
545 notes => { maxlength=>2000 },
546 }
547 } );
548 The specs allowed are fill (use this fill for the field rather than
550 the default) and maxlength (use this as the field's maxlength
551 instead of any maxlength specified in the HTML).
552 $mech->followable_links()
554 Returns a list of links that Mech can follow. This is only http and
555 https links.
556 $mech->lacks_uncapped_inputs( [$comment] )
558 Executes a test to make sure that the current form content has no text
559 input fields that lack the "maxlength" attribute, and that each
560 "maxlength" value is a positive integer. The test fails if the current
561 form has such a field, and succeeds otherwise.
562 Checks that all text input fields in the current form specify a maximum
564 input length. Fields for which the concept of input length is
565 irrelevant, and controls that HTML does not allow to be capped (e.g.
566 textarea) are ignored.
567 The return is true if the test succeeded, false otherwise.
569 $mech->check_all_images_ok( [%criterium ], [$comment] )
571 Executes a test to make sure all images in the page can be downloaded.
572 It does this by running "HEAD" requests on them. The current page
573 content stays the same.
574 The test fails if any image cannot be found, but reports all of the
576 ones that were not found.
577 For a definition of all images, see "images"in WWW::Mechanize.
579 The optional %criterium argument can be passed in before the $comment
581 and will be used to define which images should be considered. This is
582 useful to filter out specific paths.
583 $mech->check_all_images_ok( url_regex => qr{^/}, 'All absolute images should exist');
585 $mech->check_all_images_ok( url_regex => qr{\.(?:gif|jpg)$}, 'All gif and jpg images should exist');
586 $mech->check_all_images_ok(
587 url_regex => qr{^((?!\Qhttps://googleads.g.doubleclick.net/\E).)*$},
588 'All images should exist, but Ignore the ones from Doubleclick'
589 );
590 For a full list of possible arguments see "find_all_images"in
592 WWW::Mechanize.
593 The return is true if the test succeeded, false otherwise.
595
597 Other ideas for features are at
598 https://github.com/petdance/test-www-mechanize
599
601 Andy Lester, "<andy at petdance.com>"
602
604 Please report any bugs or feature requests to
605 <https://github.com/petdance/test-www-mechanize>.
606
608 You can find documentation for this module with the perldoc command.
609 perldoc Test::WWW::Mechanize
611 You can also look for information at:
613 • Bug tracker
615 <https://github.com/petdance/test-www-mechanize>
617 • CPAN Ratings
619 <http://cpanratings.perl.org/d/Test-WWW-Mechanize>
621 • Search CPAN
623 <http://search.cpan.org/dist/Test-WWW-Mechanize>
625
627 Thanks to Julien Fiegehenn, @marderh, Eric A. Zarko, @moznion, Robert
628 Stone, @tynovsky, Jerry Gay, Jonathan "Duke" Leto, Philip G. Potter,
629 Niko Tyni, Greg Sheard, Michael Schwern, Mark Blackman, Mike O'Regan,
630 Shawn Sorichetti, Chris Dolan, Matt Trout, MATSUNO Tokuhiro, and Pete
631 Krawczyk for patches.
632
634 Copyright 2004-2022 Andy Lester.
635 This library is free software; you can redistribute it and/or modify it
637 under the terms of the Artistic License version 2.0.
638perl v5.38.0 2023-07-21 Mechanize(3)