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
143 passed, 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
149 form must be found, and then submitted successfully. Otherwise, this
150 test 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
173 link must be found, and then followed successfully. Otherwise, this
174 test 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
235 should be validated by HTML::Tidy5. By default, this is just
236 "content()", but subclasses can override it to modify the content
237 before validation.
238 This method should not change any state in the Mech object.
240 Specifically, it should not actually modify any of the actual content.
241 $mech->title_is( $str [, $desc ] )
243 Tells if the title of the page is the given string.
244 $mech->title_is( 'Invoice Summary' );
246 $mech->title_like( $regex [, $desc ] )
248 Tells if the title of the page matches the given regex.
249 $mech->title_like( qr/Invoices for (.+)/ );
251 $mech->title_unlike( $regex [, $desc ] )
253 Tells if the title of the page matches the given regex.
254 $mech->title_unlike( qr/Invoices for (.+)/ );
256 $mech->base_is( $str [, $desc ] )
258 Tells if the base of the page is the given string.
259 $mech->base_is( 'http://example.com/' );
261 $mech->base_like( $regex [, $desc ] )
263 Tells if the base of the page matches the given regex.
264 $mech->base_like( qr{http://example.com/index.php?PHPSESSID=(.+)});
266 $mech->base_unlike( $regex [, $desc ] )
268 Tells if the base of the page matches the given regex.
269 $mech->base_unlike( qr{http://example.com/index.php?PHPSESSID=(.+)});
271 $mech->content_is( $str [, $desc ] )
273 Tells if the content of the page matches the given string
274 $mech->content_contains( $str [, $desc ] )
276 Tells if the content of the page contains $str.
277 $mech->content_lacks( $str [, $desc ] )
279 Tells if the content of the page lacks $str.
280 $mech->content_like( $regex [, $desc ] )
282 Tells if the content of the page matches $regex.
283 $mech->content_unlike( $regex [, $desc ] )
285 Tells if the content of the page does NOT match $regex.
286 $mech->text_contains( $str [, $desc ] )
288 Tells if the text form of the page's content contains $str.
289 When your page contains HTML which is difficult, unimportant, or
291 unlikely to match over time as designers alter markup, use
292 "text_contains" instead of "content_contains".
293 # <b>Hi, <i><a href="some/path">User</a></i>!</b>
295 $mech->content_contains('Hi, User'); # Fails.
296 $mech->text_contains('Hi, User'); # Passes.
297 Text is determined by calling "$mech->text()". See "content" in
299 WWW::Mechanize.
300 $mech->text_lacks( $str [, $desc ] )
302 Tells if the text of the page lacks $str.
303 $mech->text_like( $regex [, $desc ] )
305 Tells if the text form of the page's content matches $regex.
306 $mech->text_unlike( $regex [, $desc ] )
308 Tells if the text format of the page's content does NOT match $regex.
309 $mech->has_tag( $tag, $text [, $desc ] )
311 Tells if the page has a $tag tag with the given content in its text.
312 $mech->has_tag_like( $tag, $regex [, $desc ] )
314 Tells if the page has a $tag tag with the given content in its text.
315 $mech->page_links_ok( [ $desc ] )
317 Follow all links on the current page and test for HTTP status 200
318 $mech->page_links_ok('Check all links');
320 $mech->page_links_content_like( $regex [, $desc ] )
322 Follow all links on the current page and test their contents for
323 $regex.
324 $mech->page_links_content_like( qr/foo/,
326 'Check all links contain "foo"' );
327 $mech->page_links_content_unlike( $regex [, $desc ] )
329 Follow all links on the current page and test their contents do not
330 contain the specified regex.
331 $mech->page_links_content_unlike(qr/Restricted/,
333 'Check all links do not contain Restricted');
334 $mech->links_ok( $links [, $desc ] )
336 Follow specified links on the current page and test for HTTP status
337 200. The links may be specified as a reference to an array containing
338 WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name.
339 my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ );
341 $mech->links_ok( \@links, 'Check all links for cnn.com' );
342 my @links = qw( index.html search.html about.html );
344 $mech->links_ok( \@links, 'Check main links' );
345 $mech->links_ok( 'index.html', 'Check link to index' );
347 $mech->link_status_is( $links, $status [, $desc ] )
349 Follow specified links on the current page and test for HTTP status
350 passed. The links may be specified as a reference to an array
351 containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
352 URL name.
353 my @links = $mech->followable_links();
355 $mech->link_status_is( \@links, 403,
356 'Check all links are restricted' );
357 $mech->link_status_isnt( $links, $status [, $desc ] )
359 Follow specified links on the current page and test for HTTP status
360 passed. The links may be specified as a reference to an array
361 containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
362 URL name.
363 my @links = $mech->followable_links();
365 $mech->link_status_isnt( \@links, 404,
366 'Check all links are not 404' );
367 $mech->link_content_like( $links, $regex [, $desc ] )
369 Follow specified links on the current page and test the resulting
370 content of each against $regex. The links may be specified as a
371 reference to an array containing WWW::Mechanize::Link objects, an array
372 of URLs, or a scalar URL name.
373 my @links = $mech->followable_links();
375 $mech->link_content_like( \@links, qr/Restricted/,
376 'Check all links are restricted' );
377 $mech->link_content_unlike( $links, $regex [, $desc ] )
379 Follow specified links on the current page and test that the resulting
380 content of each does not match $regex. The links may be specified as a
381 reference to an array containing WWW::Mechanize::Link objects, an array
382 of URLs, or a scalar URL name.
383 my @links = $mech->followable_links();
385 $mech->link_content_unlike( \@links, qr/Restricted/,
386 'No restricted links' );
387
389 $mech->scrape_text_by_attr( $attr, $attr_value [, $html ] )
390 $mech->scrape_text_by_attr( $attr, $attr_regex [, $html ] )
391 Returns a list of strings, each string the text surrounded by an
392 element with attribute $attr of value $value. You can also pass in a
393 regular expression. If nothing is found the return is an empty list.
394 In scalar context the return is the first string found.
395 If passed, $html is scraped instead of the current page's content.
397 $mech->scrape_text_by_id( $id [, $html ] )
399 Finds all elements with the given ID attribute and pulls out the text
400 that that element encloses.
401 In list context, returns a list of all strings found. In scalar
403 context, returns the first one found.
404 If $html is not provided then the current content is used.
406 $mech->scraped_id_is( $id, $expected [, $msg] )
408 Scrapes the current page for given ID and tests that it matches the
409 expected value.
410 $mech->scraped_id_like( $id, $expected_regex [, $msg] )
412 Scrapes the current page for given id and tests that it matches the
413 expected regex.
414 $mech->id_exists( $id )
416 Returns TRUE/FALSE if the given ID exists in the given HTML, or if none
417 is provided, then the current page.
418 The Mech object caches the IDs so that it doesn't bother reparsing
420 every time it's asked about an ID.
421 $agent->id_exists_ok( $id [, $msg] )
423 Verifies there is an HTML element with ID $id in the page.
424 $agent->ids_exist_ok( \@ids [, $msg] )
426 Verifies an HTML element exists with each ID in "\@ids".
427 $agent->lacks_id_ok( $id [, $msg] )
429 Verifies there is NOT an HTML element with ID $id in the page.
430 $agent->lacks_ids_ok( \@ids [, $msg] )
432 Verifies there are no HTML elements with any of the ids given in
433 "\@ids".
434 $mech->button_exists( $button )
436 Returns a boolean saying whether a submit button with the name $button
437 exists. Does not do a test. For that you want "button_exists_ok" or
438 "lacks_button_ok".
439 $mech->button_exists_ok( $button [, $msg] )
441 Asserts that the button exists on the page.
442 $mech->lacks_button_ok( $button [, $msg] )
444 Asserts that no button named $button exists on the page.
445
447 $mech->autolint( [$status] )
448 Without an argument, this method returns a true or false value
449 indicating whether autolint is active.
450 When passed an argument, autolint is turned on or off depending on
452 whether the argument is true or false, and the previous autolint status
453 is returned. As with the autolint option of "new", $status can be an
454 HTML::Lint object.
455 If autolint is currently using an HTML::Lint object you provided, the
457 return is that object, so you can change and exactly restore autolint
458 status:
459 my $old_status = $mech->autolint( 0 );
461 ... operations that should not be linted ...
462 $mech->autolint( $old_status );
463 $mech->autotidy( [$status] )
465 Without an argument, this method returns a true or false value
466 indicating whether autotidy is active.
467 When passed an argument, autotidy is turned on or off depending on
469 whether the argument is true or false, and the previous autotidy status
470 is returned. As with the autotidy option of "new", $status can be an
471 HTML::Tidy5 object.
472 If autotidy is currently using an HTML::Tidy5 object you provided, the
474 return is that object, so you can change and exactly restore autotidy
475 status:
476 my $old_status = $mech->autotidy( 0 );
478 ... operations that should not be tidied ...
479 $mech->autotidy( $old_status );
480 $mech->grep_inputs( \%properties )
482 Returns a list of all the input controls in the current form whose
483 properties match all of the regexes in $properties. The controls
484 returned are all descended from HTML::Form::Input.
485 If $properties is undef or empty then all inputs will be returned.
487 If there is no current page, there is no form on the current page, or
489 there are no submit controls in the current form then the return will
490 be an empty list.
491 # Get all text controls whose names begin with "customer".
493 my @customer_text_inputs =
494 $mech->grep_inputs( {
495 type => qr/^(text|textarea)$/,
496 name => qr/^customer/
497 }
498 );
499 $mech->grep_submits( \%properties )
501 grep_submits() does the same thing as grep_inputs() except that it only
502 returns controls that are submit controls, ignoring other types of
503 input controls like text and checkboxes.
504 $mech->stuff_inputs( [\%options] )
506 Finds all free-text input fields (text, textarea, and password) in the
507 current form and fills them to their maximum length in hopes of finding
508 application code that can't handle it. Fields with no maximum length
509 and all textarea fields are set to 66000 bytes, which will often be
510 enough to overflow the data's eventual receptacle.
511 There is no return value.
513 If there is no current form then nothing is done.
515 The hashref $options can contain the following keys:
517 • ignore
519 hash value is arrayref of field names to not touch, e.g.:
521 $mech->stuff_inputs( {
523 ignore => [qw( specialfield1 specialfield2 )],
524 } );
525 • fill
527 hash value is default string to use when stuffing fields. Copies
529 of the string are repeated up to the max length of each field.
530 E.g.:
531 $mech->stuff_inputs( {
533 fill => '@' # stuff all fields with something easy to recognize
534 } );
535 • specs
537 hash value is arrayref of hashrefs with which you can pass detailed
539 instructions about how to stuff a given field. E.g.:
540 $mech->stuff_inputs( {
542 specs=>{
543 # Some fields are datatype-constrained. It's most common to
544 # want the field stuffed with valid data.
545 widget_quantity => { fill=>'9' },
546 notes => { maxlength=>2000 },
547 }
548 } );
549 The specs allowed are fill (use this fill for the field rather than
551 the default) and maxlength (use this as the field's maxlength
552 instead of any maxlength specified in the HTML).
553 $mech->followable_links()
555 Returns a list of links that Mech can follow. This is only http and
556 https links.
557 $mech->lacks_uncapped_inputs( [$comment] )
559 Executes a test to make sure that the current form content has no text
560 input fields that lack the "maxlength" attribute, and that each
561 "maxlength" value is a positive integer. The test fails if the current
562 form has such a field, and succeeds otherwise.
563 Checks that all text input fields in the current form specify a maximum
565 input length. Fields for which the concept of input length is
566 irrelevant, and controls that HTML does not allow to be capped (e.g.
567 textarea) are ignored.
568 The return is true if the test succeeded, false otherwise.
570 $mech->check_all_images_ok( [%criterium ], [$comment] )
572 Executes a test to make sure all images in the page can be downloaded.
573 It does this by running "HEAD" requests on them. The current page
574 content stays the same.
575 The test fails if any image cannot be found, but reports all of the
577 ones that were not found.
578 For a definition of all images, see "images"in WWW::Mechanize.
580 The optional %criterium argument can be passed in before the $comment
582 and will be used to define which images should be considered. This is
583 useful to filter out specific paths.
584 $mech->check_all_images_ok( url_regex => qr{^/}, 'All absolute images should exist');
586 $mech->check_all_images_ok( url_regex => qr{\.(?:gif|jpg)$}, 'All gif and jpg images should exist');
587 $mech->check_all_images_ok(
588 url_regex => qr{^((?!\Qhttps://googleads.g.doubleclick.net/\E).)*$},
589 'All images should exist, but Ignore the ones from Doubleclick'
590 );
591 For a full list of possible arguments see "find_all_images"in
593 WWW::Mechanize.
594 The return is true if the test succeeded, false otherwise.
596
598 Other ideas for features are at
599 https://github.com/petdance/test-www-mechanize
600
602 Andy Lester, "<andy at petdance.com>"
603
605 Please report any bugs or feature requests to
606 <https://github.com/petdance/test-www-mechanize>.
607
609 You can find documentation for this module with the perldoc command.
610 perldoc Test::WWW::Mechanize
612 You can also look for information at:
614 • Bug tracker
616 <https://github.com/petdance/test-www-mechanize>
618 • CPAN Ratings
620 <http://cpanratings.perl.org/d/Test-WWW-Mechanize>
622 • Search CPAN
624 <http://search.cpan.org/dist/Test-WWW-Mechanize>
626
628 Thanks to Julien Fiegehenn, @marderh, Eric A. Zarko, @moznion, Robert
629 Stone, @tynovsky, Jerry Gay, Jonathan "Duke" Leto, Philip G. Potter,
630 Niko Tyni, Greg Sheard, Michael Schwern, Mark Blackman, Mike O'Regan,
631 Shawn Sorichetti, Chris Dolan, Matt Trout, MATSUNO Tokuhiro, and Pete
632 Krawczyk for patches.
633
635 Copyright 2004-2022 Andy Lester.
636 This library is free software; you can redistribute it and/or modify it
638 under the terms of the Artistic License version 2.0.
639perl v5.36.0 2022-12-17 Mechanize(3)