1Test::WWW::Mechanize::PUSsGeIr(3C)ontributed Perl DocumeTnetsatt:i:oWnWW::Mechanize::PSGI(3)
2
6 Test::WWW::Mechanize::PSGI - Test PSGI programs using WWW::Mechanize
7
9 version 0.39
10
12 # We're in a t/*.t test script...
13 use Test::WWW::Mechanize::PSGI;
14 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
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 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 $mech->get_ok('/action');
49 $mech->get_ok('http://localhost/action');
50 This makes testing fast and easy. Test::WWW::Mechanize provides
52 functions for common web testing scenarios. For example:
53 $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 An alternative to this module is Plack::Test.
60
62 new
63 Behaves like, and calls, WWW::Mechanize's "new" method. You should pass
64 in your application:
65 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
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 A default description of "GET $url" is used if none if provided.
82 $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 A default description of "HEAD $url" is used if none if provided.
90 $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 A default description of "POST to $url" is used if none if provided.
98 $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 A default description of "PUT to $url" is used if none if provided.
106 $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 %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 $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 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 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 $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 %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 $mech->follow_link_ok( {n=>3}, "looking for 3rd link" );
141 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 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 click_ok( $button[, $desc] )
150 Clicks the button named by $button. An optional $desc can be given for
151 the test.
152
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 Note that HTML::Lint must be installed for this to work. Otherwise, it
160 will blow up.
161 $mech->title_is( $str [, $desc ] )
163 Tells if the title of the page is the given string.
164 $mech->title_is( "Invoice Summary" );
166 $mech->title_like( $regex [, $desc ] )
168 Tells if the title of the page matches the given regex.
169 $mech->title_like( qr/Invoices for (.+)/
171 $mech->title_unlike( $regex [, $desc ] )
173 Tells if the title of the page matches the given regex.
174 $mech->title_unlike( qr/Invoices for (.+)/
176 $mech->base_is( $str [, $desc ] )
178 Tells if the base of the page is the given string.
179 $mech->base_is( "http://example.com/" );
181 $mech->base_like( $regex [, $desc ] )
183 Tells if the base of the page matches the given regex.
184 $mech->base_like( qr{http://example.com/index.php?PHPSESSID=(.+)});
186 $mech->base_unlike( $regex [, $desc ] )
188 Tells if the base of the page matches the given regex.
189 $mech->base_unlike( qr{http://example.com/index.php?PHPSESSID=(.+)});
191 $mech->content_is( $str [, $desc ] )
193 Tells if the content of the page matches the given string
194 $mech->content_contains( $str [, $desc ] )
196 Tells if the content of the page contains $str.
197 $mech->content_lacks( $str [, $desc ] )
199 Tells if the content of the page lacks $str.
200 $mech->content_like( $regex [, $desc ] )
202 Tells if the content of the page matches $regex.
203 $mech->content_unlike( $regex [, $desc ] )
205 Tells if the content of the page does NOT match $regex.
206 $mech->has_tag( $tag, $text [, $desc ] )
208 Tells if the page has a $tag tag with the given content in its text.
209 $mech->has_tag_like( $tag, $regex [, $desc ] )
211 Tells if the page has a $tag tag with the given content in its text.
212 $mech->followable_links()
214 Returns a list of links that WWW::Mechanize can follow. This is only
215 http and https links.
216 $mech->page_links_ok( [ $desc ] )
218 Follow all links on the current page and test for HTTP status 200
219 $mech->page_links_ok('Check all links');
221 $mech->page_links_content_like( $regex [, $desc ] )
223 Follow all links on the current page and test their contents for
224 $regex.
225 $mech->page_links_content_like( qr/foo/,
227 'Check all links contain "foo"' );
228 $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 my @links = $mech->find_all_links( url_regex => qr/cnn\.com$/ );
235 $mech->links_ok( \@links, 'Check all links for cnn.com' );
236 my @links = qw( index.html search.html about.html );
238 $mech->links_ok( \@links, 'Check main links' );
239 $mech->links_ok( 'index.html', 'Check link to index' );
241 $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 my @links = $mech->followable_links();
249 $mech->link_status_is( \@links, 403,
250 'Check all links are restricted' );
251 $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 my @links = $mech->followable_links();
259 $mech->link_status_isnt( \@links, 404,
260 'Check all links are not 404' );
261 $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 my @links = $mech->followable_links();
269 $mech->link_content_like( \@links, qr/Restricted/,
270 'Check all links are restricted' );
271 $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 my @links = $mech->followable_links();
279 $mech->link_content_unlike( \@links, qr/Restricted/,
280 'No restricted links' );
281 $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 There is no return value.
290 If there is no current form then nothing is done.
292 The hashref $options can contain the following keys:
294 • ignore
296 hash value is arrayref of field names to not touch, e.g.:
298 $mech->stuff_inputs( {
300 ignore => [qw( specialfield1 specialfield2 )],
301 } );
302 • fill
304 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 $mech->stuff_inputs( {
310 fill => '@' # stuff all fields with something easy to recognize
311 } );
312 • specs
314 hash value is arrayref of hashrefs with which you can pass detailed
316 instructions about how to stuff a given field. E.g.:
317 $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 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
332 Leon Brocard <acme@astray.com>
333
335 This software is copyright (c) 2009 by Leon Brocard.
336 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.
339perl v5.36.0 2023-01-20 Test::WWW::Mechanize::PSGI(3)