1Test::WWW::Mechanize::PUSsGeIr(3C)ontributed Perl DocumeTnetsatt:i:oWnWW::Mechanize::PSGI(3)
2
3
4

NAME

6       Test::WWW::Mechanize::PSGI - Test PSGI programs using WWW::Mechanize
7

VERSION

9       version 0.39
10

SYNOPSIS

12         # We're in a t/*.t test script...
13         use Test::WWW::Mechanize::PSGI;
14
15         my $mech = Test::WWW::Mechanize::PSGI->new(
16             app => sub {
17                 my $env = shift;
18                 return [
19                     200,
20                     [ 'Content-Type' => 'text/html' ],
21                     [ '<html><head><title>Hi</title></head><body>Hello World</body></html>'
22                     ]
23                 ];
24             },
25         );
26         $mech->get_ok('/');
27         is( $mech->ct, 'text/html', 'Is text/html' );
28         $mech->title_is('Hi');
29         $mech->content_contains('Hello World');
30         # ... and all other Test::WWW::Mechanize methods
31

DESCRIPTION

33       PSGI is a specification to decouple web server environments from web
34       application framework code. Test::WWW::Mechanize is a subclass of
35       WWW::Mechanize that incorporates features for web application testing.
36       The Test::WWW::Mechanize::PSGI module meshes the two to allow easy
37       testing of PSGI applications.
38
39       Testing web applications has always been a bit tricky, normally
40       requiring starting a web server for your application and making real
41       HTTP requests to it. This module allows you to test PSGI web
42       applications but does not require a server or issue HTTP requests.
43       Instead, it passes the HTTP request object directly to PSGI. Thus you
44       do not need to use a real hostname: "http://localhost/" will do.
45       However, this is optional. The following two lines of code do exactly
46       the same thing:
47
48         $mech->get_ok('/action');
49         $mech->get_ok('http://localhost/action');
50
51       This makes testing fast and easy. Test::WWW::Mechanize provides
52       functions for common web testing scenarios. For example:
53
54         $mech->get_ok( $page );
55         $mech->title_is( "Invoice Status", "Make sure we're on the invoice page" );
56         $mech->content_contains( "Andy Lester", "My name somewhere" );
57         $mech->content_like( qr/(cpan|perl)\.org/, "Link to perl.org or CPAN" );
58
59       An alternative to this module is Plack::Test.
60

CONSTRUCTOR

62   new
63       Behaves like, and calls, WWW::Mechanize's "new" method. You should pass
64       in your application:
65
66         my $mech = Test::WWW::Mechanize::PSGI->new(
67             app => sub {
68                 my $env = shift;
69                 return [ 200, [ 'Content-Type' => 'text/plain' ], ['Hello World'] ],;
70             },
71             env => { REMOTE_USER => 'Foo Bar' },
72         );
73

METHODS: HTTP VERBS

75   $mech->get_ok($url, [ \%LWP_options ,] $desc)
76       A wrapper around WWW::Mechanize's get(), with similar options, except
77       the second argument needs to be a hash reference, not a hash. Like
78       well-behaved *_ok() functions, it returns true if the test passed, or
79       false if not.
80
81       A default description of "GET $url" is used if none if provided.
82
83   $mech->head_ok($url, [ \%LWP_options ,] $desc)
84       A wrapper around WWW::Mechanize's head(), with similar options, except
85       the second argument needs to be a hash reference, not a hash. Like
86       well-behaved *_ok() functions, it returns true if the test passed, or
87       false if not.
88
89       A default description of "HEAD $url" is used if none if provided.
90
91   $mech->post_ok( $url, [ \%LWP_options ,] $desc )
92       A wrapper around WWW::Mechanize's post(), with similar options, except
93       the second argument needs to be a hash reference, not a hash. Like
94       well-behaved *_ok() functions, it returns true if the test passed, or
95       false if not.
96
97       A default description of "POST to $url" is used if none if provided.
98
99   $mech->put_ok( $url, [ \%LWP_options ,] $desc )
100       A wrapper around WWW::Mechanize's put(), with similar options, except
101       the second argument needs to be a hash reference, not a hash. Like
102       well-behaved *_ok() functions, it returns true if the test passed, or
103       false if not.
104
105       A default description of "PUT to $url" is used if none if provided.
106
107   $mech->submit_form_ok( \%params [, $desc] )
108       Makes a submit_form() call and executes tests on the results.  The form
109       must be found, and then submitted successfully.  Otherwise, this test
110       fails.
111
112       %params is a hashref containing the params to pass to submit_form().
113       Note that the params to submit_form() are a hash whereas the params to
114       this function are a hashref.  You have to call this function like:
115
116           $agent->submit_form_ok({
117               form_number => 3,
118               fields      => {
119                   username    => 'mungo',
120                   password    => 'lost-and-alone',
121               }
122           }, "looking for 3rd form" );
123
124       As with other test functions, $desc is optional.  If it is supplied
125       then it will display when running the test harness in verbose mode.
126
127       Returns true value if the specified link was found and followed
128       successfully.  The HTTP::Response object returned by submit_form() is
129       not available.
130
131   $mech->follow_link_ok( \%params [, $desc] )
132       Makes a follow_link() call and executes tests on the results.  The link
133       must be found, and then followed successfully.  Otherwise, this test
134       fails.
135
136       %params is a hashref containing the params to pass to follow_link().
137       Note that the params to follow_link() are a hash whereas the params to
138       this function are a hashref.  You have to call this function like:
139
140           $mech->follow_link_ok( {n=>3}, "looking for 3rd link" );
141
142       As with other test functions, $desc is optional.  If it is supplied
143       then it will display when running the test harness in verbose mode.
144
145       Returns a true value if the specified link was found and followed
146       successfully.  The HTTP::Response object returned by follow_link() is
147       not available.
148
149   click_ok( $button[, $desc] )
150       Clicks the button named by $button.  An optional $desc can be given for
151       the test.
152

METHODS: CONTENT CHECKING

154   $mech->html_lint_ok( [$desc] )
155       Checks the validity of the HTML on the current page.  If the page is
156       not HTML, then it fails.  The URI is automatically appended to the
157       $desc.
158
159       Note that HTML::Lint must be installed for this to work.  Otherwise, it
160       will blow up.
161
162   $mech->title_is( $str [, $desc ] )
163       Tells if the title of the page is the given string.
164
165           $mech->title_is( "Invoice Summary" );
166
167   $mech->title_like( $regex [, $desc ] )
168       Tells if the title of the page matches the given regex.
169
170           $mech->title_like( qr/Invoices for (.+)/
171
172   $mech->title_unlike( $regex [, $desc ] )
173       Tells if the title of the page matches the given regex.
174
175           $mech->title_unlike( qr/Invoices for (.+)/
176
177   $mech->base_is( $str [, $desc ] )
178       Tells if the base of the page is the given string.
179
180           $mech->base_is( "http://example.com/" );
181
182   $mech->base_like( $regex [, $desc ] )
183       Tells if the base of the page matches the given regex.
184
185           $mech->base_like( qr{http://example.com/index.php?PHPSESSID=(.+)});
186
187   $mech->base_unlike( $regex [, $desc ] )
188       Tells if the base of the page matches the given regex.
189
190           $mech->base_unlike( qr{http://example.com/index.php?PHPSESSID=(.+)});
191
192   $mech->content_is( $str [, $desc ] )
193       Tells if the content of the page matches the given string
194
195   $mech->content_contains( $str [, $desc ] )
196       Tells if the content of the page contains $str.
197
198   $mech->content_lacks( $str [, $desc ] )
199       Tells if the content of the page lacks $str.
200
201   $mech->content_like( $regex [, $desc ] )
202       Tells if the content of the page matches $regex.
203
204   $mech->content_unlike( $regex [, $desc ] )
205       Tells if the content of the page does NOT match $regex.
206
207   $mech->has_tag( $tag, $text [, $desc ] )
208       Tells if the page has a $tag tag with the given content in its text.
209
210   $mech->has_tag_like( $tag, $regex [, $desc ] )
211       Tells if the page has a $tag tag with the given content in its text.
212
213   $mech->followable_links()
214       Returns a list of links that WWW::Mechanize can follow.  This is only
215       http and https links.
216
217   $mech->page_links_ok( [ $desc ] )
218       Follow all links on the current page and test for HTTP status 200
219
220           $mech->page_links_ok('Check all links');
221
222   $mech->page_links_content_like( $regex [, $desc ] )
223       Follow all links on the current page and test their contents for
224       $regex.
225
226           $mech->page_links_content_like( qr/foo/,
227             'Check all links contain "foo"' );
228
229   $mech->links_ok( $links [, $desc ] )
230       Follow specified links on the current page and test for HTTP status
231       200.  The links may be specified as a reference to an array containing
232       WWW::Mechanize::Link objects, an array of URLs, or a scalar URL name.
233
234           my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ );
235           $mech->links_ok( \@links, 'Check all links for cnn.com' );
236
237           my @links = qw( index.html search.html about.html );
238           $mech->links_ok( \@links, 'Check main links' );
239
240           $mech->links_ok( 'index.html', 'Check link to index' );
241
242   $mech->link_status_is( $links, $status [, $desc ] )
243       Follow specified links on the current page and test for HTTP status
244       passed.  The links may be specified as a reference to an array
245       containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
246       URL name.
247
248           my @links = $mech->followable_links();
249           $mech->link_status_is( \@links, 403,
250             'Check all links are restricted' );
251
252   $mech->link_status_isnt( $links, $status [, $desc ] )
253       Follow specified links on the current page and test for HTTP status
254       passed.  The links may be specified as a reference to an array
255       containing WWW::Mechanize::Link objects, an array of URLs, or a scalar
256       URL name.
257
258           my @links = $mech->followable_links();
259           $mech->link_status_isnt( \@links, 404,
260             'Check all links are not 404' );
261
262   $mech->link_content_like( $links, $regex [, $desc ] )
263       Follow specified links on the current page and test the resulting
264       content of each against $regex.  The links may be specified as a
265       reference to an array containing WWW::Mechanize::Link objects, an array
266       of URLs, or a scalar URL name.
267
268           my @links = $mech->followable_links();
269           $mech->link_content_like( \@links, qr/Restricted/,
270               'Check all links are restricted' );
271
272   $mech->link_content_unlike( $links, $regex [, $desc ] )
273       Follow specified links on the current page and test that the resulting
274       content of each does not match $regex.  The links may be specified as a
275       reference to an array containing WWW::Mechanize::Link objects, an array
276       of URLs, or a scalar URL name.
277
278           my @links = $mech->followable_links();
279           $mech->link_content_unlike( \@links, qr/Restricted/,
280             'No restricted links' );
281
282   $mech->stuff_inputs( [\%options] )
283       Finds all free-text input fields (text, textarea, and password) in the
284       current form and fills them to their maximum length in hopes of finding
285       application code that can't handle it.  Fields with no maximum length
286       and all textarea fields are set to 66000 bytes, which will often be
287       enough to overflow the data's eventual receptacle.
288
289       There is no return value.
290
291       If there is no current form then nothing is done.
292
293       The hashref $options can contain the following keys:
294
295       •   ignore
296
297           hash value is arrayref of field names to not touch, e.g.:
298
299               $mech->stuff_inputs( {
300                   ignore => [qw( specialfield1 specialfield2 )],
301               } );
302
303       •   fill
304
305           hash value is default string to use when stuffing fields.  Copies
306           of the string are repeated up to the max length of each field.
307           E.g.:
308
309               $mech->stuff_inputs( {
310                   fill => '@'  # stuff all fields with something easy to recognize
311               } );
312
313       •   specs
314
315           hash value is arrayref of hashrefs with which you can pass detailed
316           instructions about how to stuff a given field.  E.g.:
317
318               $mech->stuff_inputs( {
319                   specs=>{
320                       # Some fields are datatype-constrained.  It's most common to
321                       # want the field stuffed with valid data.
322                       widget_quantity => { fill=>'9' },
323                       notes => { maxlength=>2000 },
324                   }
325               } );
326
327           The specs allowed are fill (use this fill for the field rather than
328           the default) and maxlength (use this as the field's maxlength
329           instead of any maxlength specified in the HTML).
330

AUTHOR

332       Leon Brocard <acme@astray.com>
333
335       This software is copyright (c) 2009 by Leon Brocard.
336
337       This is free software; you can redistribute it and/or modify it under
338       the same terms as the Perl 5 programming language system itself.
339
340
341
342perl v5.36.0                      2023-01-20     Test::WWW::Mechanize::PSGI(3)
Impressum