.\" Automatically generated by Pod::Man version 1.15
.\" Fri Nov 18 12:08:59 2005
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD. Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.bd B 3
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "SIMPLE_SCAN 1"
.TH SIMPLE_SCAN 1 "perl v5.6.1" "2005-11-17" "User Contributed Perl Documentation"
.UC
.SH "NAME"
simple_scan \- scan a set of Web pages for strings present/absent
.SH "ABSTRACT"
.IX Header "ABSTRACT"
App::SimpleScan \- Mini-language for website testing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& simple_scan [--generate] [--run] {file file file ...}
.Ve
.SH "USAGE"
.IX Header "USAGE"
.Vb 3
\& # Run the tests in the files supplied on the command line.
\& # --run (or -run; we're flexible) is assumed if you give no switches.
\& % simple_scan file1 file2 file3
.Ve
.Vb 2
\& # Generate a set of tests and save them, then run them.
\& % <complex pipe> | simple_scan --generate > pipe_scan.t
.Ve
.Vb 2
\& # Run one simple test
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`simple_scan\*(C'\fR reads either files supplied on the command line, or standard
input. It creates and runs, or prints, or even both, a the Test::WWW::Simple manpage
test for the criteria supplied to it.
.PP
\&\f(CW\*(C`simple_scan\*(C'\fR's input should be in the following format:
.PP
.Vb 1
\& <URL> <pattern> <Y|N> <comment>
.Ve
The \fI\s-1URL\s0\fR is any \s-1URL\s0; \fIpattern\fR is a Perl regular expression, delimited by
slashes; \fIY|N\fR is \f(CW\*(C`Y\*(C'\fR if the pattern should match, or \f(CW\*(C`N\*(C'\fR if the pattern
should \fBnot\fR match; and \fIcomment\fR is any arbitrary text you like (as long
as it's all on the same line as everything else).
.PP
\&\f(CW\*(C`simple_scan\*(C'\fRwill do its best to try to interpret your pattern; if it can't
parse it as a regular expression, it will assume you meant to match against
a literal character string instead; so a pattern like
.PP
.Vb 1
\& /<b>this</b>/
.Ve
Would be interpreted as the literal string \*(L"<b>this</b>\*(R".
.SH "COMMAND-LINE SWITCHES"
.IX Header "COMMAND-LINE SWITCHES"
We use the Getopt::Long manpage to get the command-line options, so we're really very
flexible as to how they're entered. You can use either one dash (as in
\&\f(CW\*(C`\-foo\*(C'\fR) or two (as in \f(CW\*(C`\-\-bar\*(C'\fR). You only need to enter the minimum number
or characters to match a given switch.
.if n .Ip "\f(CW""""\-\-run""""\fR" 4
.el .Ip "\f(CW\-\-run\fR" 4
.IX Item "--run"
\&\f(CW\*(C`\-\-run\*(C'\fR tells \f(CW\*(C`simple_scan\*(C'\fR to immediately run the tests it's created. Can
be abbreviated to \f(CW\*(C`\-r\*(C'\fR.
.Sp
This option is mosst useful for one-shot tests that you're not planning to
run repeatedly.
.if n .Ip "\f(CW""""\-\-generate""""\fR" 4
.el .Ip "\f(CW\-\-generate\fR" 4
.IX Item "--generate"
\&\f(CW\*(C`\-\-generate\*(C'\fR tells \f(CW\*(C`simple_scan\*(C'\fR to print the test it's generated on the
standard output.
.Sp
This option is useful to build up a test suite to be reused later.
.PP
Both \f(CW\*(C`\-r\*(C'\fR and \f(CW\*(C`\-g\*(C'\fR can be specified at the same time to run a test and print
it simultaneously; this is useful when you want to save a test to be run later
as well as right now without having to regenerate the test.
.if n .Ip "\f(CW""""\-\-define""""\fR" 4
.el .Ip "\f(CW\-\-define\fR" 4
.IX Item "--define"
\&\f(CW\*(C`\-\-define\*(C'\fR allows you to predefine substitutions to be used during a
\&\f(CW\*(C`simple_scan\*(C'\fR run. To define a substitution, use this syntax:
.Sp
.Vb 1
\& --define foo=bar --define baz="one two three"
.Ve
The first example defines a single substitution; the second defines a
multiple substitution. In conjunction with \f(CW\*(C`\-\-override\*(C'\fR, \f(CW\*(C`\-\-define\*(C'\fR
can make \f(CW\*(C`simple_scan\*(C'\fR ignore any definitions for variables in the
\&\f(CW\*(C`simple_scan\*(C'\fR input file. Conversely, if \f(CW\*(C`\-\-defer\*(C'\fR is specified,
any definitions on the command line will be altered if a definition
for the variable is found in the input file.
.Sp
Note that \f(CW\*(C`%%forget\*(C'\fR can still make \f(CW\*(C`simple_scan\*(C'\fR forget a definition
(if \f(CW\*(C`App::SimpleScan::Plugin::Forget\*(C'\fR is installed).
.Sp
Also note that you define a variable with multiple values like this:
.Sp
.Vb 1
\& --define foo="bar baz quux"
.Ve
but\fBnot\fR like this:
.Sp
.Vb 1
\& --define foo=bar --define foo=baz --define foo=quux
.Ve
since multiple definitions of a single substitution use only the
\&\fIlast\fR substitution defined; the example directly above (with
the three \*(L"\-\-define\*(R" entries) defines \*(L"foo\*(R" as \*(L"quux\*(R" and only
as \*(L"quux\*(R".
.if n .Ip "\f(CW""""\-\-override""""\fR" 4
.el .Ip "\f(CW\-\-override\fR" 4
.IX Item "--override"
Makes any definitions entered on the command line override definitions
found in the input file.
.if n .Ip "\f(CW""""\-\-defer""""\fR" 4
.el .Ip "\f(CW\-\-defer\fR" 4
.IX Item "--defer"
Makes any definitions entered on the command line defer to defintions
found in the input file \- the variables in question will be redefined
by the command file.
.if n .Ip "\f(CW""""\-\-debug""""\fR" 4
.el .Ip "\f(CW\-\-debug\fR" 4
.IX Item "--debug"
Enables debugging for you \f(CW\*(C`simple_scan\*(C'\fR input file; this outputs a
lot of extra code which, when executed by \f(CW\*(C`simple_scan \-\-run\*(C'\fR, shows
a lot more information as to what actually happened.
.Sp
Currently, the only extra debugging information is a list of variables
which were \fInot\fR altered by substitution pragmas when \f(CW\*(C`\-\-override\*(C'\fR
was specified on the command line.
.if n .Ip "\f(CW""""\-\-autocache""""\fR" 4
.el .Ip "\f(CW\-\-autocache\fR" 4
.IX Item "--autocache"
Turns on caching immediately, whether or not the input file specifies
\&\f(CW\*(C`%%cache\*(C'\fR or not. Note that a \f(CW\*(C`%%nocache\*(C'\fR in the input file will
turn caching \fIoff\fR again.
.SH "PRAGMAS"
.IX Header "PRAGMAS"
Pragmas are ways to influence what \f(CW\*(C`simple_scan\*(C'\fR does when generating tests.
They don't output anything themselves.
.PP
Pragmas are specified with \f(CW\*(C`%%\*(C'\fR in column 1 and the pragma name immediately
following. Any arguments aer supplied after a colon, like this:
.PP
.Vb 1
\& %%foo: bar baz
.Ve
This invokes the \f(CW\*(C`foo\*(C'\fR pragma with the argument \f(CW\*(C`bar baz\*(C'\fR.
.Sh "Substitutions"
.IX Subsection "Substitutions"
Any pragma that's otherwise unrecognized by \f(CW\*(C`simple_scan\*(C'\fR is treated as a
substitution. Substitutions assume that you have a name and a set of strings
following it; these strings wil be substituted into the test specs occuring
between this (set) of substitutions and the next (set).
.PP
Here's an example.
.PP
.Vb 6
\& %% user dconway chromatic petdance
\& %% use_perl_id Ovid pemungkah
\& ...
.Ve
This would fetch the \s-1CPAN\s0 index page for the users dconway, chromatic, and
petdance, and the use.perl journals for users Ovid and pemungkah. Finally,
it would (just once) fetch the Yahoo! search page \- because there are no
substitutions in that line, it would only be evaluated once.
.PP
The substitutions can occur anywhere in the line, including in the comment.
.PP
This pragma allows for very simple-minded internationalization. For instance,
let's assume that you want to substitute each of a list of two-character
country codes into a string (most likely somewhere in the \s-1URL\s0, but possibly
in the comment too).
.PP
\&\f(CW\*(C`simple_scan\*(C'\fR will do this for you, creating a test for each country code
you specify. For instance:
.PP
.Vb 2
\& %%xx: es au my jp
\& http://>xx<.mysite.com/ /blargh/ Y look for blargh (>xx<).Ve
This would generate 4 tests, for \f(CW\*(C`es.mysite.com\*(C'\fR, \f(CW\*(C`au.mysite.com\*(C'\fR,
c<my.mysite.com>, and \f(CW\*(C`jp.mysite.com\*(C'\fR, all looking to match \f(CW\*(C`blargh\*(C'\fR
somewhere on the page.
.Sh "agent"
.IX Subsection "agent"
The \f(CW\*(C`agent\*(C'\fR pragma allows you to switch user agents during the test.
\&\f(CW\*(C`Test::WWW::Simple\*(C'\fR's default is \f(CW\*(C`Windows IE 6\*(C'\fR, but you can switch it
to any of the other user agents supported by \f(CW\*(C`WWW::Mechanize\*(C'\fR.
.PP
.Vb 3
\& %%agent: Mac Safari
.Ve
.Sh "cache"
.IX Subsection "cache"
The \f(CW\*(C`cache\*(C'\fR pragma turns on \s-1URL\s0 caching; once enabled, the page returned
on the \fIfirst\fR access to a \s-1URL\s0 is returned directly from a memory cache,
without its being reaccessed from the Web.
.PP
Using \f(CW\*(C`cache\*(C'\fR can result in major speedups for tests which repeatedly
hit the same page.
.Sh "nocache"
.IX Subsection "nocache"
The \f(CW\*(C`nocache\*(C'\fR pragma turns \fIoff\fR \s-1URL\s0 caching; this is useful if you
have something like a \s-1REST\s0 interface that may return different values
from repeated accesses to the same \s-1URL\s0.
.SH "AUTHOR"
.IX Header "AUTHOR"
Joe McMahon <mcmahon@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2005 by Yahoo!
.PP
This script is free software; you can redistribute it or modify it under the
same terms as Perl itself, either Perl version 5.6.1 or, at your option, any
later version of Perl 5 you may have available.