1Mechanize(3) User Contributed Perl Documentation Mechanize(3)
2
6 Test::WWW::Mechanize - Testing-specific WWW::Mechanize subclass
7
9 Version 1.54
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 an array 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 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 the submit $button exists. Does not do
437 a test. For that you want "button_exists_ok" or "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 the 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 grep_inputs() returns an array of all the input controls in the current
482 form whose properties match all of the regexes in $properties. The
483 controls 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 array.
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 inputs in the returned array are descended from HTML::Form::Input.
569 The return is true if the test succeeded, false otherwise.
571
573 Add HTML::Tidy capabilities.
574 Other ideas for features are at
576 https://github.com/petdance/test-www-mechanize
577
579 Andy Lester, "<andy at petdance.com>"
580
582 Please report any bugs or feature requests to
583 <https://github.com/petdance/test-www-mechanize>.
584
586 You can find documentation for this module with the perldoc command.
587 perldoc Test::WWW::Mechanize
589 You can also look for information at:
591 · Bug tracker
593 <https://github.com/petdance/test-www-mechanize>
595 · CPAN Ratings
597 <http://cpanratings.perl.org/d/Test-WWW-Mechanize>
599 · Search CPAN
601 <http://search.cpan.org/dist/Test-WWW-Mechanize>
603
605 Thanks to @marderh, Eric A. Zarko, @moznion, Robert Stone, @tynovsky,
606 Jerry Gay, Jonathan "Duke" Leto, Philip G. Potter, Niko Tyni, Greg
607 Sheard, Michael Schwern, Mark Blackman, Mike O'Regan, Shawn Sorichetti,
608 Chris Dolan, Matt Trout, MATSUNO Tokuhiro, and Pete Krawczyk for
609 patches.
610
612 Copyright 2004-2020 Andy Lester.
613 This library is free software; you can redistribute it and/or modify it
615 under the terms of the Artistic License version 2.0.
616perl v5.32.0 2020-12-15 Mechanize(3)