blib/lib/App/SimpleScan/Cookbook.pm

filter: Statementstmt 100% 4 / 4 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 1 / 1 Podpod n/a totaltotal 100% 5 / 5 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
CRAP 1.0
« bin/simple_scan ↑ Summary
1 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
2  
3 =head1 NAME
4  
5 App::SimpleScan::Cookbook
6  
7 =head1 DESCRIPTION
8  
9 This is a documentation-only module that describes how to use C<simple_scan>,
10 and outlines some techniques you can use for some common Web testing problems.
11  
12 =head1 BASICS
13  
14 C<simple_scan> reads I<test specifications> from standard input and generates
15 Perl code based on these specifications. It can either
16  
17 =over 4
18  
19 =item * execute them immediately,
20  
21 =item * print them on standard output without executing them,
22  
23 =item * or do both: execute them and then print the generated code on standard output.
24  
25 =back
26  
27 =head1 TEST SPECS
28  
29 Test specifications describe
30  
31 =over 4
32  
33 =item * I<where> the page is that you want to check,
34  
35 =item * some I<content> (in the form of a Perl regular expression) that you want look for
36  
37 =item * a "success code", which defines whether or not the regex should match, and optionally allows you to run the test as a TODO, or skip it altogether.
38  
39 =over
40  
41 =item Y - The regular expression should match.
42  
43 =item N - The regular expression should I<not> match.
44  
45 =item TY - This a "TODO" test; eventually the regular expression should match, but isn't expected to now. (If it does, C<simple_report> will not that a test "UNEXPECTEDLY SUCCEEDED".)
46  
47 =item TN - This "TODO" test is expected to match now, but eventually should not. (If it fails to match, this is also an "unexpected success".)
48  
49 =item S - This test is to be skipped. Useful for putting in a placeholder test tht you don't currently want to run. This is usually useful when you have a test which is expensive or slow to run, and which you know currently will not pass.
50  
51 =back
52  
53 =item * and a comment about why you care
54  
55 =back
56  
57 C<simple_scan> always uses an HTTP GET to access the URL; if you need to do stuff like log in, or other setup that requires any other HTTP action, you'll need to use a plugin (see below).
58  
59 Note that TODO tests get run whether or not they will pass; we just mind if
60 they currently fail. Skipped tests are not run at all. Use skipped tests if you
61 want to save time; use TODO tests if you want to be alerted of a change (from
62 passing to failing or vice versa).
63  
64 Some example test specs:
65  
66 http://foobar.com?q=zorch&xx=yy /\d+ foobars found/ Y Check zorch query
67 http://perl.org/ /Perl/ Y Perl mentioned here
68 http://python.org/ /Perl/ N Not mentioned here
69  
70 =head1 PRAGMAS
71  
72 You can use pragmas to control how tests are executed. Pragmas start with '%%'
73 at the beginning of the line, followed by a pragma name and arguments if the
74 pragma takes any. C<simple_scan> itself provides 3 pragmas:
75  
76 =over
77  
78 =item agent
79  
80 This tells C<simple_scan> what User-Agent string to use. Because remembering
81 all the fiddly bits is a pain, you can simply use shortcut names, like
82 "Safari", "Mozilla", or "IE"; the actual list is the one supported by
83 X<WWW::Mechanize>'s agent_alias() method.
84  
85 =item cache
86  
87 Stacks a call to cache() in the tests built by C<simple_scan>. This tells
88 C<simple_scan> to hang onto the last copy of the page fetched from every URL;
89 if the URL is hit multiple times during a test, C<simple_scan> fetches it only
90 once and then reuses the cached copy for further tests.
91  
92 =item nocache
93  
94 Turns off caching by stacking a nocache() call in the tests built.
95 C<simple_scan> will always refetch every URL when nocache() is in force.
96  
97 =back
98  
99 Here's a sample test using the base pragmas:
100  
101 %%agent Safari
102 http://apple.com/html5 /download Safar/ N No Safari warning with Safari
103 %%cache
104 %%agent IE
105 http://apple.com/html5 /download Safar/ Y Safari warning with IE
106 http://apple.com/html5 /HTML5 Showcase/ Y uses cached copy
107 %%nocache
108 http://apple.com/html5 /takes a few/ Y uses a new copy
109  
110 =head1 VARIABLE SUBSITUTION
111  
112 You can define substitutions much like you'd use a pragma:
113  
114 %%site apple
115 %%subsite html5
116 http://<site>.com/<subsite> /HTML5 Showcase/ Y Apple's HTML5 showcase
117  
118 The twist with C<simple_scan> variables is that they can have multiple values:
119  
120 %%query foo bar baz
121 http://foobar.com/q=<query> /<query> found/ Y Found <query>
122  
123 This causes C<simple_scan> to generate code to run three tests, one for each of
124 the values of the 'query' variable. Notice that we can substitute into any
125 part of the test specification; in this case we didn't substitute into the
126 test type, but it's as valid as any other part of the line.
127  
128 If you have multiple variables with multiple values, C<simple_scan> will
129 generate the Cartesian product of them:
130  
131 %%foo one two three four
132 %%bar alpha beta gamma delta epsilon
133 %%baz now is the time for all good men
134 http://sample-site.org?q=<foo><bar>baz> /Found:/ Y Looking for <foo>, <bar>, <baz>
135  
136 This generates 4 * 5 * 8 = 160 tests in just 4 lines.
137  
138 Pragmas may expand into other pragmas; the previous example could have been
139 written as
140  
141 %%foo one two three four
142 %%bar alpha beta gamma delta epsilon
143 %%baz now is the time for all good men
144 %%query <foo><bar><baz>
145 http://sample-site.org?q=<query> ...
146  
147 In this case, the 'query' variable would have been assigned all 160 values, and
148 anything that used the 'query' variable would be expanded with all of them.
149  
150 Caution is urged in creating complex nested expansions; making these too
151 complicated can make your generated scripts very hard to debug, as there's
152 currently no easy way to track the expansions and debug them.
153  
154 =head2 Matching non-ASCII Latin-1 characters
155  
156 First: be sure that the non-ASCII character you're seeing on the screen is actually
157 present in the HTML source. You could be looking at an HTML entity that gets rendered
158 as the character in question. For instance a degree symbol is actually C<&xB0;>.
159  
160 You can match a specific entity with its actual text:
161  
162 /&x[bB]0;/
163  
164 (Note that we've made sure that it will work whether the hex "digits" are upper or
165 lowercase.) Or you can match an arbitrary entity:
166  
167 /&.*?;/
168  
169 This one will also match things like C<&amp;> and C<&brkbar;> - with great power
170 comes relative imprecision. There's a handy table of Latin-1 entities at
171 L<http://www.ramsch.org/martin/uni/fmi-hp/iso8859-1.html>.
172  
173 In some cases (e.g., Yahoo!'s fr.search search results), there will actually be
174 non-Latin1 characters that are not HTML encoded. This is probably not good
175 practice, but it still exists here and there. To deal with pages like this,
176 copy and paste the exact text from a "view source" into the regex you want
177 to use.
178  
179 Newer versions of simple_scan handle data smoothly without any special
180 action on your part, even if the encoding's off a bit.
181  
182 =head1 PLUGINS
183  
184 Plugins are Perl modules that extend C<simple_scan>'s abilities without modification of the core code.
185  
186 =head2 Installing a new pragma
187  
188 Create a C<pragmas> method in your plugin that returns pairs of pragma names and
189 methods to be called to process the pragma.
190  
191 sub pragmas {
192 return (['mypragma' => \&do_my_pragma],
193 ['another' => \&another]);
194 }
195  
196 sub do_my_pragma {
197 my ($app, $args);
198 # Parse the arguments. You have access to
199 # all of the methods in App::SimpleScan as
200 # well as any subs defined here. You may
201 # want to export methods to the App::SimpleScan
202 # namespace in your import() method.
203 }
204  
205 ...
206  
207 =head2 Installing new command-line options
208  
209 Create an C<options> method in your plugin that returns a hash of options and
210 variables to capture their values in. You will also want to export accessors
211 for these variables to the C<App::SimpleScan> namespace in your C<import>.
212  
213 sub import {
214 no strict 'refs';
215 *{caller() . '::myoption} = \&myoption;
216 }
217  
218 sub options {
219 return ('myoption' => \$myoption);
220 }
221  
222 sub myoption {
223 my ($self, $value) = @_;
224 $myoption = $value if defined $value;
225 $myoption;
226 }
227  
228 =head2 Installing other modules via plugins
229  
230 Create a C<test_modules> method that returns a list of module names
231 to be C<use>d by the generated test program.
232  
233 sub test_modules {
234 return ('Test::Foo', 'Blortch::Zonk');
235 }
236  
237 =head2 Adding extra code to the test output stack in a plugin
238  
239 Create a C<per_test> subroutine. This method gets called with the
240 current C<App::SimpleScan::TestSpec> object.
241  
242 sub per_test {
243 $self->app->_stack_test(qw(fail "forced failure accessing bad.com";\n))
244 if $self->uri =~ /bad.com/;
245 }
246  
247 =head2 Altering code/inserting code for every test stacked
248  
249 Create a C<filter> subroutine. This will get called with an array of strings
250 corresponding to the code that's about to be stacked; you can do whatever
251 additions or alterations you like. Just return your altered code as an array
252 of strings; if you've added any tests to it, use the test_count() method in the
253 app() object to up the test count appropriately.
254  
255 =head2 Current plugins available
256  
257 Currently, there are six C<simple_scan> plugins available on CPAN:
258  
259 =over
260  
261 =item Cache - the cache plugin extends C<simple_scan>'s caching to actually store the cached pages on disk. This allows subsequent runs to (if they choose) reuse pages that were fetched by previous runs. This is most useful in situations where you want to explore a number of different tests on a page, and you want to minimize the impact of your fetching the page to test it.
262  
263 =item Forget - lets you drop a substitution from the substitutions you've defined during a test run.
264  
265 =item LinkCheck - Lets you set up a set of named links that will be checked for on every page you fetch. Very useful whrn checking to make sure that (say) header and footer sections of pages are being generated correctly and consistently. You can test for the links either being there (via %%has_link) or not there (via %%no_link), and you may drop a link you've beed searching for via %%drop_link.
266  
267 =item Plaintext - lets you match vs. the plain text of a page, with the markup removed. Allows you to check content without worry if ot how it has been marked up.
268  
269 =item Retry - lets you automatically retry a URL up to a set number of times before giving up. (It also adds a --retry command-line option which does the same.)
270  
271 =item Snaphot - lets you set up to be able to automatically (either for every get, or only when there are errors) snapshot the page as it was when the GET request was made. This can be very useful in visually debugging problems with C<simple_scan> tests. See C<App::SimpleScan::Plugin::Snapshot> for detailed usage information.
272  
273 =back
274  
275 =cut
276  
277 1 1; # Allow this "module" to be loaded for POD testing
« bin/simple_scan ↑ Summary