.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 .\" .\" 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 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. . \" 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 "TESTIE 1" .TH TESTIE 1 "" "perl v5.8.7" "" .SH "NAME" testie \- simple test harness .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& testie [OPTIONS] [FILE]... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Testie is a simple test harness. Each testie test file incorporates a shell script to be run and, optionally, input and expected output files for that script. Testie runs the script; the test fails if any of the script commands fail, or if the script generates unexpected output. .PP To run testie, pass it one or more test filenames. It will print useful error messages for failed tests. Alternatively, give it directory names; the directories are recursively searched for '\fI*.testie\fR' files. .PP Return status is 0 if all tests succeed, 1 if any test fails, and 2 if a test fails due to an internal error. Tests whose \f(CW%require\fR prerequisites fail do not affect the return status, except that if all tests' prerequisites fail, the return status is 1 instead of 0. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fI\s-1VARIABLE\s0\fR=\fI\s-1VALUE\s0\fR" 8 .IX Item "VARIABLE=VALUE" Provide a setting for \fI\s-1VARIABLE\s0\fR. Occurrences in the script of \&'\f(CW$VARIABLE\fR' or '\f(CW\*(C`${VARIABLE}\*(C'\fR' will be replaced by \fI\s-1VALUE\s0\fR. Note that this is not an environment variable setting. Variable references to unset variables are left unchanged. .IP "\-V, \-\-verbose" 8 .IX Item "-V, --verbose" Print information to standard error about successful tests as well as unsuccessful tests. .IP "\-VV, \-\-superverbose" 8 .IX Item "-VV, --superverbose" Like \-\-verbose, but use a slightly different format, and additionally print every test's \f(CW%desc\fR section before the test results. .IP "\-v, \-\-version" 8 .IX Item "-v, --version" Print version number information and exit. .IP "\-\-help" 8 .IX Item "--help" Print help information and exit. .IP "\-\-preserve\-temporaries" 8 .IX Item "--preserve-temporaries" Preserve the temporary directory created for the test. .IP "\-s, \-\-show \s-1FILE\s0" 8 .IX Item "-s, --show FILE" Echo the contents of \s-1FILE\s0 on completion. \s-1FILE\s0 should be one of the filenames specified by \f(CW%file\fR or \f(CW%expect\fR*, or 'stdout' or 'stderr'. .IP "\-e, \-\-expand" 8 .IX Item "-e, --expand" Don't run the given test; instead, expand its files into the current directory. The script is stored in a file called '+script+'. .SH "FILE FORMAT" .IX Header "FILE FORMAT" Testie test files consist of several sections, each introduced by a line starting with %. There must be, at least, a \f(CW%script\fR section. .PP The \f(CW%file\fR and \f(CW%expect\fR* sections define input and/or output files by name. Testie runs its script in a private directory in \fI/tmp\fR; any files mentioned in \f(CW%file\fR or \f(CW%expect\fR* are placed in that directory. .IP "%script" 8 .IX Item "%script" The shell script (in sh syntax) that controls the test. Testie will run each command in sequence. Every command in the script must succeed, with exit status 0, or the test will fail. The script's inputs and outputs are defined with the \f(CW%file\fR and \f(CW%expect\fR* sections. .IP "%require [\-q]" 8 .IX Item "%require [-q]" A shell script (in sh syntax) defining prerequisites that must be satisfied before the test can run. Every command in the script must succeed, with exit status 0, for the test to run. \f(CW%require\fR's output is not checked, however. The \f(CW\*(C`\-q\*(C'\fR flag tells testie not to print an error message if a requirement fails. .IP "%desc" 8 .IX Item "%desc" A short description of the test. In \-\-superverbose mode, its contents are printed before the test results. .IP "%info" 8 .IX Item "%info" This section is ignored. It is intended for information about the test. .IP "%cut" 8 .IX Item "%cut" This section is ignored. It is intended to comment out obsolete parts of the test. .IP "%file [\-d] [+LENGTH] \s-1FILENAME\s0..." 8 .IX Item "%file [-d] [+LENGTH] FILENAME..." Create an input file for the script. \s-1FILENAME\s0 can be 'stdin', which sets the script's standard input. If \s-1LENGTH\s0 is provided, the file data consists of the \s-1LENGTH\s0 bytes following this line. Otherwise, it consists of the data up to the next section. The \f(CW\*(C`\-d\*(C'\fR flag tells testie to delete the first character of each line in the section; this makes it possible to include files that have lines that start with %. \s-1FILENAME\s0 cannot contain slashes. .IP "%expectv [\-a] [\-d] [+LENGTH] \s-1FILENAME\s0..." 8 .IX Item "%expectv [-a] [-d] [+LENGTH] FILENAME..." An expected output file for the script. \s-1FILENAME\s0 can be 'stdout', for standard output. If \s-1LENGTH\s0 is provided, the file data consists of the \&\s-1LENGTH\s0 bytes following this line; otherwise, it consists of the data up to the next section. .Sp Testie will run the script, then compare the script's output file with the provided data. They must match exactly or the test fails. .Sp The \f(CW\*(C`\-a\*(C'\fR flag marks this expected output as an alternate. Testie will compare the script's output file with each provided alternate; the test succeeds if any of the alternates match. The \f(CW\*(C`\-d\*(C'\fR flag behaves as in \&\f(CW%file\fR. .IP "%expect [\-a] [\-d] [\-i] [+LENGTH] \s-1FILENAME\s0..." 8 .IX Item "%expect [-a] [-d] [-i] [+LENGTH] FILENAME..." An expected output file for the script. Arguments are as for \f(CW%expectv\fR. .Sp Testie will run the script, then compare the file generated by script with the provided data. The files are compared line\-by\-line. Testie ignores trailing whitespace on each line and in the files at large. It also ignores lines in the script output that match \f(CW%ignore\fR patterns (see below). Blank lines in the \f(CW%expect\fR data match one or more blank lines in the output. \f(CW%expect\fR lines can contain Perl regular expressions, enclosed by two sets of braces; so the \f(CW%expect\fR line .Sp .Vb 1 \& foo{{(bar)?}} .Ve .Sp matches either 'foo' or 'foobar'. The \f(CW\*(C`\-i\*(C'\fR flag makes any regular expressions case\-insensitive. .IP "%expectx [\-a] [\-d] [\-i] [+LENGTH] \s-1FILENAME\s0..." 8 .IX Item "%expectx [-a] [-d] [-i] [+LENGTH] FILENAME..." %expectx is just like \f(CW%expect\fR, except that every line is treated as a regular expression (so there is no need for the \*(L"{{ }}\*(R" escapes). .IP "%stdin [+LENGTH]" 8 .IX Item "%stdin [+LENGTH]" Same as '%file stdin [\s-1ARGS\s0]'. .IP "%stdout [\-a] [\-d] [\-i] [+LENGTH]" 8 .IX Item "%stdout [-a] [-d] [-i] [+LENGTH]" Same as '%expect stdout'. .IP "%stderr [\-a] [\-d] [\-i] [+LENGTH]" 8 .IX Item "%stderr [-a] [-d] [-i] [+LENGTH]" Same as '%expect stderr'. .IP "%ignore [\-d] [\-i] [+LENGTH] [\s-1FILENAME\s0]" 8 .IX Item "%ignore [-d] [-i] [+LENGTH] [FILENAME]" Each line in the \f(CW%ignore\fR section is a Perl regular expression. Lines in the supplied \s-1FILENAME\s0 that match any of those regular expressions will not be considered when comparing files with \f(CW%expect\fR[x] data. The regular expression must match the whole line. \s-1FILENAME\s0 may be 'all', in which case the regular expressions will apply to all \f(CW%expect\fR[x] files. .IP "%eot" 8 .IX Item "%eot" Marks the end of the current test. The rest of the file will be parsed for additional tests. .IP "%eof" 8 .IX Item "%eof" The rest of the file is ignored. .SH "EXAMPLE" .IX Header "EXAMPLE" This simple testie script checks that 'grep \-c' works for a simple output file. .PP .Vb 7 \& %script \& grep \-c B. \& %stdin \& Bfoo \& B \& %stdout \& 1 .Ve .SH "AUTHOR" .IX Header "AUTHOR" Eddie Kohler,