1Mechanize(3)          User Contributed Perl Documentation         Mechanize(3)
2
3
4

NAME

6       Test::WWW::Mechanize - Testing-specific WWW::Mechanize subclass
7

VERSION

9       Version 1.52
10

SYNOPSIS

12       Test::WWW::Mechanize is a subclass of WWW::Mechanize that incorporates
13       features for web application testing.  For example:
14
15           use Test::More tests => 5;
16           use Test::WWW::Mechanize;
17
18           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
25       This is equivalent to:
26
27           use Test::More tests => 5;
28           use WWW::Mechanize;
29
30           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
38       but has nicer diagnostics if they fail.
39
40       Default descriptions will be supplied for most methods if you omit
41       them. e.g.
42
43           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
50       results in
51
52           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

CONSTRUCTOR

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
63       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
67           my $lint = HTML::Lint->new( only_types => HTML::Lint::Error::STRUCTURE );
68           my $mech = Test::WWW::Mechanize->new( autolint => $lint );
69
70       The same is also possible with "autotidy => 1" to use HTML::Tidy5.
71
72       ·   get_ok()
73
74       ·   post_ok()
75
76       ·   submit_form_ok()
77
78       ·   follow_link_ok()
79
80       ·   click_ok()
81
82       This means you no longer have to do the following:
83
84           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
88       and can simply do
89
90           my $mech = Test::WWW::Mechanize->new( autolint => 1 );
91           $mech->get_ok( $url, 'Fetch the intro page' );
92
93       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
97       You can control autolint and autotidy on the fly with the "autolint"
98       and "autotidy" methods.
99

METHODS: HTTP VERBS

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
107       A default description of "GET $url" is used if none if provided.
108
109   $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
115       A default description of "HEAD $url" is used if none if provided.
116
117   $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
123       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
129       A default description of "POST to $url" is used if none if provided.
130
131   $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
137       A default description of "PUT to $url" is used if none if provided.
138
139   $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
145       A default description of "DELETE to $url" is used if none if provided.
146
147   $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
152       %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
156           $mech->submit_form_ok( {
157                   form_number => 3,
158                   fields      => {
159                       answer => 42
160                   },
161               }, 'now we just need the question'
162           );
163
164       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
167       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
171   $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
176       %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
180           $mech->follow_link_ok( {n=>3}, 'looking for 3rd link' );
181
182       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
185       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
189   $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
194           $mech->click_ok( 'continue', 'Clicking the "Continue" button' );
195
196       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
200           $mech->click_ok( [ 'continue', 12, 47 ], 'Clicking the "Continue" button' );
201

METHODS: HEADER CHECKING

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
207   $mech->lacks_header_ok( $header [, $desc ] )
208       Assures that a given response header does NOT exist.
209
210   $mech->header_is( $header, $value [, $desc ] )
211       Assures that a given response header exists and has the given value.
212
213   $mech->header_like( $header, $value [, $desc ] )
214       Assures that a given response header exists and has the given value.
215

METHODS: CONTENT CHECKING

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
222       Note that HTML::Lint must be installed for this to work.  Otherwise, it
223       will blow up.
224
225   $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
230       Note that HTML::tidy must be installed for this to work.  Otherwise, it
231       will blow up.
232
233   $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
239       This method should not change any state in the Mech object.
240       Specifically, it should not actually modify any of the actual content.
241
242   $mech->title_is( $str [, $desc ] )
243       Tells if the title of the page is the given string.
244
245           $mech->title_is( 'Invoice Summary' );
246
247   $mech->title_like( $regex [, $desc ] )
248       Tells if the title of the page matches the given regex.
249
250           $mech->title_like( qr/Invoices for (.+)/ );
251
252   $mech->title_unlike( $regex [, $desc ] )
253       Tells if the title of the page matches the given regex.
254
255           $mech->title_unlike( qr/Invoices for (.+)/ );
256
257   $mech->base_is( $str [, $desc ] )
258       Tells if the base of the page is the given string.
259
260           $mech->base_is( 'http://example.com/' );
261
262   $mech->base_like( $regex [, $desc ] )
263       Tells if the base of the page matches the given regex.
264
265           $mech->base_like( qr{http://example.com/index.php?PHPSESSID=(.+)});
266
267   $mech->base_unlike( $regex [, $desc ] )
268       Tells if the base of the page matches the given regex.
269
270           $mech->base_unlike( qr{http://example.com/index.php?PHPSESSID=(.+)});
271
272   $mech->content_is( $str [, $desc ] )
273       Tells if the content of the page matches the given string
274
275   $mech->content_contains( $str [, $desc ] )
276       Tells if the content of the page contains $str.
277
278   $mech->content_lacks( $str [, $desc ] )
279       Tells if the content of the page lacks $str.
280
281   $mech->content_like( $regex [, $desc ] )
282       Tells if the content of the page matches $regex.
283
284   $mech->content_unlike( $regex [, $desc ] )
285       Tells if the content of the page does NOT match $regex.
286
287   $mech->text_contains( $str [, $desc ] )
288       Tells if the text form of the page's content contains $str.
289
290       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
294        # <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
298       Text is determined by calling "$mech->text()".  See "content" in
299       WWW::Mechanize.
300
301   $mech->text_lacks( $str [, $desc ] )
302       Tells if the text of the page lacks $str.
303
304   $mech->text_like( $regex [, $desc ] )
305       Tells if the text form of the page's content matches $regex.
306
307   $mech->text_unlike( $regex [, $desc ] )
308       Tells if the text format of the page's content does NOT match $regex.
309
310   $mech->has_tag( $tag, $text [, $desc ] )
311       Tells if the page has a $tag tag with the given content in its text.
312
313   $mech->has_tag_like( $tag, $regex [, $desc ] )
314       Tells if the page has a $tag tag with the given content in its text.
315
316   $mech->page_links_ok( [ $desc ] )
317       Follow all links on the current page and test for HTTP status 200
318
319           $mech->page_links_ok('Check all links');
320
321   $mech->page_links_content_like( $regex [, $desc ] )
322       Follow all links on the current page and test their contents for
323       $regex.
324
325           $mech->page_links_content_like( qr/foo/,
326             'Check all links contain "foo"' );
327
328   $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
332           $mech->page_links_content_unlike(qr/Restricted/,
333             'Check all links do not contain Restricted');
334
335   $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
340           my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ );
341           $mech->links_ok( \@links, 'Check all links for cnn.com' );
342
343           my @links = qw( index.html search.html about.html );
344           $mech->links_ok( \@links, 'Check main links' );
345
346           $mech->links_ok( 'index.html', 'Check link to index' );
347
348   $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
354           my @links = $mech->followable_links();
355           $mech->link_status_is( \@links, 403,
356             'Check all links are restricted' );
357
358   $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
364           my @links = $mech->followable_links();
365           $mech->link_status_isnt( \@links, 404,
366             'Check all links are not 404' );
367
368   $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
374           my @links = $mech->followable_links();
375           $mech->link_content_like( \@links, qr/Restricted/,
376               'Check all links are restricted' );
377
378   $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
384           my @links = $mech->followable_links();
385           $mech->link_content_unlike( \@links, qr/Restricted/,
386             'No restricted links' );
387

METHODS: SCRAPING

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
396       If passed, $html is scraped instead of the current page's content.
397
398   $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
402       In list context, returns a list of all strings found. In scalar
403       context, returns the first one found.
404
405       If $html is not provided then the current content is used.
406
407   $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
411   $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
415   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
419       The Mech object caches the IDs so that it doesn't bother reparsing
420       every time it's asked about an ID.
421
422   $agent->id_exists_ok( $id [, $msg] )
423       Verifies there is an HTML element with ID $id in the page.
424
425   $agent->ids_exist_ok( \@ids [, $msg] )
426       Verifies an HTML element exists with each ID in "\@ids".
427
428   $agent->lacks_id_ok( $id [, $msg] )
429       Verifies there is NOT an HTML element with ID $id in the page.
430
431   $agent->lacks_ids_ok( \@ids [, $msg] )
432       Verifies there are no HTML elements with any of the ids given in
433       "\@ids".
434
435   $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
439   $mech->button_exists_ok( $button [, $msg] )
440       Asserts that the button exists on the page.
441
442   $mech->lacks_button_ok( $button [, $msg] )
443       Asserts that the button exists on the page.
444

METHODS: MISCELLANEOUS

446   $mech->autolint( [$status] )
447       Without an argument, this method returns a true or false value
448       indicating whether autolint is active.
449
450       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
455       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
459           my $old_status = $mech->autolint( 0 );
460           ... operations that should not be linted ...
461           $mech->autolint( $old_status );
462
463   $mech->autotidy( [$status] )
464       Without an argument, this method returns a true or false value
465       indicating whether autotidy is active.
466
467       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
472       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
476           my $old_status = $mech->autotidy( 0 );
477           ... operations that should not be tidied ...
478           $mech->autotidy( $old_status );
479
480   $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
485       If $properties is undef or empty then all inputs will be returned.
486
487       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
491           # 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
499   $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
504   $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
511       There is no return value.
512
513       If there is no current form then nothing is done.
514
515       The hashref $options can contain the following keys:
516
517       ·   ignore
518
519           hash value is arrayref of field names to not touch, e.g.:
520
521               $mech->stuff_inputs( {
522                   ignore => [qw( specialfield1 specialfield2 )],
523               } );
524
525       ·   fill
526
527           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
531               $mech->stuff_inputs( {
532                   fill => '@'  # stuff all fields with something easy to recognize
533               } );
534
535       ·   specs
536
537           hash value is arrayref of hashrefs with which you can pass detailed
538           instructions about how to stuff a given field.  E.g.:
539
540               $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
549           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
553   $mech->followable_links()
554       Returns a list of links that Mech can follow.  This is only http and
555       https links.
556
557   $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
563       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
568       The inputs in the returned array are descended from HTML::Form::Input.
569
570       The return is true if the test succeeded, false otherwise.
571

TODO

573       Add HTML::Tidy capabilities.
574
575       Other ideas for features are at
576       https://github.com/petdance/test-www-mechanize
577

AUTHOR

579       Andy Lester, "<andy at petdance.com>"
580

BUGS

582       Please report any bugs or feature requests to
583       <https://github.com/petdance/test-www-mechanize>.
584

SUPPORT

586       You can find documentation for this module with the perldoc command.
587
588           perldoc Test::WWW::Mechanize
589
590       You can also look for information at:
591
592       ·   Bug tracker
593
594           <https://github.com/petdance/test-www-mechanize>
595
596       ·   AnnoCPAN: Annotated CPAN documentation
597
598           <http://annocpan.org/dist/Test-WWW-Mechanize>
599
600       ·   CPAN Ratings
601
602           <http://cpanratings.perl.org/d/Test-WWW-Mechanize>
603
604       ·   Search CPAN
605
606           <http://search.cpan.org/dist/Test-WWW-Mechanize>
607

ACKNOWLEDGEMENTS

609       Thanks to @marderh, Eric A. Zarko, @moznion, Robert Stone, @tynovsky,
610       Jerry Gay, Jonathan "Duke" Leto, Philip G. Potter, Niko Tyni, Greg
611       Sheard, Michael Schwern, Mark Blackman, Mike O'Regan, Shawn Sorichetti,
612       Chris Dolan, Matt Trout, MATSUNO Tokuhiro, and Pete Krawczyk for
613       patches.
614
616       Copyright 2004-2018 Andy Lester.
617
618       This library is free software; you can redistribute it and/or modify it
619       under the terms of the Artistic License version 2.0.
620
621
622
623perl v5.28.1                      2018-12-05                      Mechanize(3)
Impressum