.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.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. \*(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-
.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" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" 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 "PG_PROVE 1p"
.TH PG_PROVE 1p "2022-11-27" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Name"
.IX Header "Name"
pg_prove \- A command-line tool for running and harnessing pgTAP tests
.SH "Usage"
.IX Header "Usage"
.Vb 3
\& pg_prove tests/
\& pg_prove \-\-dbname template1 test*.sql
\& pg_prove \-d testdb \-\-runtests
.Ve
.SH "Description"
.IX Header "Description"
\&\f(CW\*(C`pg_prove\*(C'\fR is a command-line application to run one or more
pgTAP tests in a PostgreSQL database. The output of the
tests is harvested and processed by TAP::Harness in order to
summarize the results of the test.
.PP
\&\f(CW\*(C`pg_prove\*(C'\fR relies on \f(CW\*(C`psql\*(C'\fR
to run the tests, and therefor supports all of the
environment variables ,
as well as the password file
and service file read
by \f(CW\*(C`psql\*(C'\fR.
.PP
Tests can be written and run in one of two ways, as \s-1SQL\s0 scripts or as
xUnit-style database functions.
.SS "Test Scripts"
.IX Subsection "Test Scripts"
pgTAP test scripts should consist of a series of \s-1SQL\s0 statements that output
\&\s-1TAP.\s0 Here's a simple example that assumes that the pgTAP functions have been
installed in the database:
.PP
.Vb 3
\& \-\- Start transaction and plan the tests.
\& BEGIN;
\& SELECT plan(1);
\&
\& \-\- Run the tests.
\& SELECT pass( \*(AqMy test passed, w00t!\*(Aq );
\&
\& \-\- Finish the tests and clean up.
\& SELECT * FROM finish();
\& ROLLBACK;
.Ve
.PP
Now run the tests by passing the list of \s-1SQL\s0 script names or the name of a
test directory to \f(CW\*(C`pg_prove\*(C'\fR. Here's what it looks like when the pgTAP tests
are run with \f(CW\*(C`pg_prove\*(C'\fR
.PP
.Vb 9
\& % pg_prove \-U postgres tests/
\& tests/coltap.....ok
\& tests/hastap.....ok
\& tests/moretap....ok
\& tests/pg73.......ok
\& tests/pktap......ok
\& All tests successful.
\& Files=5, Tests=216, 1 wallclock secs ( 0.06 usr 0.02 sys + 0.08 cusr 0.07 csys = 0.23 CPU)
\& Result: PASS
.Ve
.SS "xUnit Test Functions"
.IX Subsection "xUnit Test Functions"
pgTAP test functions should return a set of text, and then simply return the
values returned by pgTAP functions, like so:
.PP
.Vb 5
\& CREATE OR REPLACE FUNCTION setup_insert(
\& ) RETURNS SETOF TEXT AS $$
\& RETURN NEXT is( MAX(nick), NULL, \*(AqShould have no users\*(Aq) FROM users;
\& INSERT INTO users (nick) VALUES (\*(Aqtheory\*(Aq);
\& $$ LANGUAGE plpgsql;
\&
\& Create OR REPLACE FUNCTION test_user(
\& ) RETURNS SETOF TEXT AS $$
\& SELECT is( nick, \*(Aqtheory\*(Aq, \*(AqShould have nick\*(Aq) FROM users;
\& END;
\& $$ LANGUAGE sql;
.Ve
.PP
Once you have these functions defined in your database, you can run them with
\&\f(CW\*(C`pg_prove\*(C'\fR by using the \f(CW\*(C`\-\-runtests\*(C'\fR option.
.PP
.Vb 5
\& % pg_prove \-\-dbname mydb \-\-runtests
\& runtests()....ok
\& All tests successful.
\& Files=1, Tests=32, 0 wallclock secs ( 0.02 usr 0.01 sys + 0.01 cusr 0.00 csys = 0.04 CPU)
\& Result: PASS
.Ve
.PP
Be sure to pass the \f(CW\*(C`\-\-schema\*(C'\fR option if your test functions are all in one
schema, and the \f(CW\*(C`\-\-match\*(C'\fR option if they have names that don't start with
\&\*(L"test\*(R". For example, if you have all of your test functions in the \*(L"test\*(R"
schema and \fIending\fR with \*(L"test,\*(R" run the tests like so:
.PP
.Vb 1
\& pg_prove \-\-dbname mydb \-\-schema test \-\-match \*(Aqtest$\*(Aq
.Ve
.SH "Options"
.IX Header "Options"
.Vb 10
\& \-b \-\-psql\-bin PSQL Location of the psql client.
\& \-d, \-\-dbname DBNAME Database to which to connect.
\& \-U, \-\-username USERNAME User with which to connect.
\& \-h, \-\-host HOST Host to which to connect.
\& \-p, \-\-port PORT Port to which to connect.
\& \-P, \-\-pset OPTION=VALUE Set psql key/value printing option.
\& \-S, \-\-set VAR=VALUE Set variables for psql session.
\& \-R \-\-runtests Run xUnit test using runtests().
\& \-s, \-\-schema SCHEMA Schema in which to find xUnit tests.
\& \-x, \-\-match REGEX Regular expression to find xUnit tests.
\&
\& \-\-ext Set the extension for tests (default .pg)
\& \-r, \-\-recurse Recursively descend into directories.
\& \-\-ignore\-exit Ignore exit status from test scripts.
\& \-\-trap Trap Ctrl\-C and print summary on interrupt.
\& \-\-harness Define test harness to use.
\& \-j, \-\-jobs N Run N test jobs in parallel (try 9.)
\& \-\-rc RCFILE Process options from rcfile
\& \-\-norc Don\*(Aqt process default .proverc
\& \-\-state OPTION=VALUE Set persistent state options.
\&
\& \-v, \-\-verbose Print all test lines.
\& \-f, \-\-failures Show failed tests.
\& \-o, \-\-comments Show comments and diagnostics.
\& \-\-directives Only show results with TODO or SKIP directives.
\& \-q, \-\-quiet Suppress some test output while running tests.
\& \-Q, \-\-QUIET Only print summary results.
\& \-\-parse Show full list of TAP parse errors, if any.
\& \-\-normalize Normalize TAP output in verbose output
\& \-D \-\-dry Dry run. Show test that would have run.
\& \-\-merge Merge test scripts\*(Aq STDERR and STDOUT.
\& \-t \-\-timer Print elapsed time after each test.
\& \-c, \-\-color Colored test output (default).
\& \-\-nocolor Do not color test output.
\& \-\-shuffle Run the tests in random order.
\& \-\-reverse Run the tests in reverse order.
\& \-a, \-\-archive FILENAME Store the resulting TAP in an archive file.
\& \-\-formatter Result formatter to use.
\& \-\-count Show X/Y test count when not verbose (default)
\& \-\-nocount Disable the X/Y test count.
\&
\& \-H, \-\-help Print a usage statement and exit.
\& \-?, Print a usage statement and exit.
\& \-m, \-\-man Print the complete documentation and exit.
\& \-V, \-\-version Print the version number and exit.
.Ve
.SH "Options Details"
.IX Header "Options Details"
.SS "Database Options"
.IX Subsection "Database Options"
.ie n .IP """\-b""" 4
.el .IP "\f(CW\-b\fR" 4
.IX Item "-b"
.PD 0
.ie n .IP """\-\-psql\-bin""" 4
.el .IP "\f(CW\-\-psql\-bin\fR" 4
.IX Item "--psql-bin"
.PD
.Vb 2
\& pg_prove \-\-psql\-bin /usr/local/pgsql/bin/psql
\& pg_prove \-b /usr/local/bin/psql
.Ve
.Sp
Path to the \f(CW\*(C`psql\*(C'\fR program, which will be used to actually run the tests.
Defaults to \fIpsql\fR, which should work well, when it is in your path.
.ie n .IP """\-d""" 4
.el .IP "\f(CW\-d\fR" 4
.IX Item "-d"
.PD 0
.ie n .IP """\-\-dbname""" 4
.el .IP "\f(CW\-\-dbname\fR" 4
.IX Item "--dbname"
.PD
.Vb 2
\& pg_prove \-\-dbname try
\& pg_prove \-d postgres
.Ve
.Sp
The name of database to which to connect. Defaults to the value of the
\&\f(CW$PGDATABASE\fR environment variable or to the system username.
.ie n .IP """\-U""" 4
.el .IP "\f(CW\-U\fR" 4
.IX Item "-U"
.PD 0
.ie n .IP """\-\-username""" 4
.el .IP "\f(CW\-\-username\fR" 4
.IX Item "--username"
.PD
.Vb 2
\& pg_prove \-\-username foo
\& pg_prove \-U postgres
.Ve
.Sp
PostgreSQL user name to connect as. Defaults to the value of the \f(CW$PGUSER\fR
environment variable or to the operating system name of the user running the
application.
.ie n .IP """\-h""" 4
.el .IP "\f(CW\-h\fR" 4
.IX Item "-h"
.PD 0
.ie n .IP """\-\-host""" 4
.el .IP "\f(CW\-\-host\fR" 4
.IX Item "--host"
.PD
.Vb 2
\& pg_prove \-\-host pg.example.com
\& pg_prove \-h dev.local
.Ve
.Sp
Specifies the host name of the machine on which the server is running. If the
value begins with a slash, it is used as the directory for the Unix-domain
socket. Defaults to the value of the \f(CW$PGHOST\fR environment variable or
localhost.
.ie n .IP """\-p""" 4
.el .IP "\f(CW\-p\fR" 4
.IX Item "-p"
.PD 0
.ie n .IP """\-\-port""" 4
.el .IP "\f(CW\-\-port\fR" 4
.IX Item "--port"
.PD
.Vb 2
\& pg_prove \-\-port 1234
\& pg_prove \-p 666
.Ve
.Sp
Specifies the \s-1TCP\s0 port or the local Unix-domain socket file extension on which
the server is listening for connections. Defaults to the value of the
\&\f(CW$PGPORT\fR environment variable or, if not set, to the port specified at
compile time, usually 5432.
.ie n .IP """\-P""" 4
.el .IP "\f(CW\-P\fR" 4
.IX Item "-P"
.PD 0
.ie n .IP """\-\-pset""" 4
.el .IP "\f(CW\-\-pset\fR" 4
.IX Item "--pset"
.PD
.Vb 2
\& pg_prove \-\-pset tuples_only=0
\& pg_prove \-P null=[NULL]
.Ve
.Sp
Specifies printing options in the style of \f(CW\*(C`\epset\*(C'\fR in the \f(CW\*(C`psql\*(C'\fR program.
See for details
on the supported options.
.ie n .IP """\-S""" 4
.el .IP "\f(CW\-S\fR" 4
.IX Item "-S"
.PD 0
.ie n .IP """\-\-set""" 4
.el .IP "\f(CW\-\-set\fR" 4
.IX Item "--set"
.PD
.Vb 2
\& pg_prove \-\-set MY_CONTRACT=321
\& pg_prove \-S TEST_SEARCH_PATH=test,public
.Ve
.Sp
Sets local variables for psql in the style of \f(CW\*(C`\eset\*(C'\fR in the \f(CW\*(C`psql\*(C'\fR program.
See for details
on the supported options.
.ie n .IP """\-\-runtests""" 4
.el .IP "\f(CW\-\-runtests\fR" 4
.IX Item "--runtests"
.Vb 2
\& pg_prove \-\-runtests
\& pg_prove \-r
.Ve
.Sp
Don't run any test scripts, but just use the \f(CW\*(C`runtests()\*(C'\fR pgTAP function to
run xUnit tests. This ends up looking like a single test script has been run,
when in fact no test scripts have been run. Instead, \f(CW\*(C`pg_prove\*(C'\fR tells \f(CW\*(C`psql\*(C'\fR
to run something like:
.Sp
.Vb 1
\& psql \-\-command \*(AqSELECT * FROM runtests()\*(Aq
.Ve
.Sp
You should use this option when you've written your tests in xUnit style,
where they're all defined in test functions already loaded in the database.
.ie n .IP """\-s""" 4
.el .IP "\f(CW\-s\fR" 4
.IX Item "-s"
.PD 0
.ie n .IP """\-\-schema""" 4
.el .IP "\f(CW\-\-schema\fR" 4
.IX Item "--schema"
.PD
.Vb 2
\& pg_prove \-\-schema test
\& pg_prove \-s mytest
.Ve
.Sp
Used with \f(CW\*(C`\-\-runtests\*(C'\fR, and, in fact, implicitly forces \f(CW\*(C`\-\-runtests\*(C'\fR to be
true. This option can be used to specify the name of a schema in which to find
xUnit functions to run. Basically, it tells \f(CW\*(C`psql\*(C'\fR to run something like:
.Sp
.Vb 1
\& psql \-\-command "SELECT * FROM runtests(\*(Aqtest\*(Aq::name)"
.Ve
.ie n .IP """\-x""" 4
.el .IP "\f(CW\-x\fR" 4
.IX Item "-x"
.PD 0
.ie n .IP """\-\-match""" 4
.el .IP "\f(CW\-\-match\fR" 4
.IX Item "--match"
.PD
.Vb 2
\& pg_prove \-\-match \*(Aqtest$\*(Aq
\& pg_prove \-x _test_
.Ve
.Sp
Used with \f(CW\*(C`\-\-runtests\*(C'\fR, and, in fact, implicitly forces \f(CW\*(C`\-\-runtests\*(C'\fR to be
true. This option can be used to specify a \s-1POSIX\s0 regular expression that will
be used to search for xUnit functions to run. Basically, it tells \f(CW\*(C`psql\*(C'\fR to
run something like:
.Sp
.Vb 1
\& psql \-\-command "SELECT * FROM runtests(\*(Aq_test_\*(Aq::text)"
.Ve
.Sp
This will run any visible functions with the string \*(L"_test_\*(R" in their names.
This can be especially useful if you just want to run a single test in a
given schema. For example, this:
.Sp
.Vb 1
\& pg_prove \-\-schema testing \-\-match \*(Aq^test_widgets$\*(Aq
.Ve
.Sp
Will have \f(CW\*(C`psql\*(C'\fR execute the \f(CW\*(C`runtests()\*(C'\fR function like so:
.Sp
.Vb 1
\& SELECT * FROM runtests(\*(Aqtesting\*(Aq::name, \*(Aq^test_widgets$\*(Aq::text);
.Ve
.SS "Behavioral Options"
.IX Subsection "Behavioral Options"
.ie n .IP """\-\-ext""" 4
.el .IP "\f(CW\-\-ext\fR" 4
.IX Item "--ext"
.Vb 1
\& pg_prove \-\-ext .sql tests/
.Ve
.Sp
Set the extension for test files (default \fI.pg\fR). May be specified multiple
times if you have test scripts with multiple extensions, though all must be
pgTAP tests:
.Sp
.Vb 1
\& pg_prove \-\-ext .sql \-\-ext .pg \-\-ext .pgt
.Ve
.Sp
If you want to mix pgTAP tests with other TAP-emitting tests, like Perl tests,
use \f(CW\*(C`prove\*(C'\fR instead, where \f(CW\*(C`\-\-ext\*(C'\fR identifies any test file, and
\&\f(CW\*(C`\-\-pgtap\-option suffix=\*(C'\fR lets you specify one or more extensions for pgTAP
tests.
.Sp
.Vb 3
\& prove \-\-source Perl \e
\& \-\-ext .t \-\-ext .pg \e
\& \-\-source pgTAP \-\-pgtap\-option suffix=.pg
.Ve
.ie n .IP """\-r""" 4
.el .IP "\f(CW\-r\fR" 4
.IX Item "-r"
.PD 0
.ie n .IP """\-\-recurse""" 4
.el .IP "\f(CW\-\-recurse\fR" 4
.IX Item "--recurse"
.PD
.Vb 2
\& pg_prove \-\-recurse tests/
\& pg_prove \-\-recurse sql/
.Ve
.Sp
Recursively descend into directories when searching for tests. Be sure to
specify \f(CW\*(C`\-\-ext\*(C'\fR if your tests do not end in \f(CW\*(C`.pg\*(C'\fR. Not relevant with
\&\f(CW\*(C`\-\-runtests\*(C'\fR.
.ie n .IP """\-\-ignore\-exit""" 4
.el .IP "\f(CW\-\-ignore\-exit\fR" 4
.IX Item "--ignore-exit"
.Vb 1
\& pg_prove \-\-ignore\-exit
.Ve
.Sp
Ignore exit status from test scripts. Normally if a script triggers a database
exception, \f(CW\*(C`psql\*(C'\fR will exit with an error code and, even if all tests passed,
the test will be considered a failure. Use \f(CW\*(C`\-\-ignore\-exit\*(C'\fR to ignore such
situations (at your own peril).
.ie n .IP """\-\-trap""" 4
.el .IP "\f(CW\-\-trap\fR" 4
.IX Item "--trap"
.Vb 1
\& pg_prove \-\-trap
.Ve
.Sp
Trap \f(CW\*(C`Ctrl\-C\*(C'\fR and print a summary on interrupt.
.ie n .IP """\-\-harness""" 4
.el .IP "\f(CW\-\-harness\fR" 4
.IX Item "--harness"
.Vb 1
\& pg_prove \-\-harness TAP::Harness::Color
.Ve
.Sp
Specify a subclass of TAP::Harness to use for the test harness. Defaults to
TAP::Harness (unless \f(CW\*(C`\-\-archive\*(C'\fR is specified, in which case it uses
TAP::Harness::Archive).
.ie n .IP """\-j""" 4
.el .IP "\f(CW\-j\fR" 4
.IX Item "-j"
.PD 0
.ie n .IP """\-jobs""" 4
.el .IP "\f(CW\-jobs\fR" 4
.IX Item "-jobs"
.PD
Run N test jobs in parallel (try 9.)
.ie n .IP """\-\-rc""" 4
.el .IP "\f(CW\-\-rc\fR" 4
.IX Item "--rc"
.Vb 1
\& pg_prove \-\-rc pg_prove.rc
.Ve
.Sp
Process options from the specified configuration file.
.Sp
If \f(CW\*(C`\-\-rc\*(C'\fR is not specified and \fI./.proverc\fR or \fI~/.proverc\fR exist, they
will be read and the options they contain processed before the command line
options. Options in configuration files are specified in the same way as
command line options:
.Sp
.Vb 3
\& # .proverc
\& \-\-state=hot,fast,save
\& \-j9
.Ve
.Sp
Under Windows and \s-1VMS\s0 the option file is named \fI_proverc\fR rather than
\&\fI.proverc\fR and is sought only in the current directory.
.Sp
Due to how options are loaded you cannot use \fI.proverc\fR for
\&\f(CW\*(C`pg_prove\*(C'\fR\-specific options, only \f(CW\*(C`prove\*(C'\fR options. However, does
support all of the usual libpq
Environment Variables .
.ie n .IP """\-\-norc""" 4
.el .IP "\f(CW\-\-norc\fR" 4
.IX Item "--norc"
Do not process \fI./.proverc\fR or \fI~/.proverc\fR.
.ie n .IP """\-\-state""" 4
.el .IP "\f(CW\-\-state\fR" 4
.IX Item "--state"
You can ask \f(CW\*(C`pg_prove\*(C'\fR to remember the state of previous test runs and select
and/or order the tests to be run based on that saved state.
.Sp
The \f(CW\*(C`\-\-state\*(C'\fR switch requires an argument which must be a comma separated
list of one or more of the following options.
.RS 4
.ie n .IP """last""" 4
.el .IP "\f(CWlast\fR" 4
.IX Item "last"
Run the same tests as the last time the state was saved. This makes it
possible, for example, to recreate the ordering of a shuffled test.
.Sp
.Vb 2
\& # Run all tests in random order
\& pg_prove \-\-state save \-\-shuffle
\&
\& # Run them again in the same order
\& pg_prove \-\-state last
.Ve
.ie n .IP """failed""" 4
.el .IP "\f(CWfailed\fR" 4
.IX Item "failed"
Run only the tests that failed on the last run.
.Sp
.Vb 2
\& # Run all tests
\& pg_prove \-\-state save
\&
\& # Run failures
\& pg_prove \-\-state failed
.Ve
.Sp
If you also specify the \f(CW\*(C`save\*(C'\fR option newly passing tests will be
excluded from subsequent runs.
.Sp
.Vb 2
\& # Repeat until no more failures
\& pg_prove \-\-state failed,save
.Ve
.ie n .IP """passed""" 4
.el .IP "\f(CWpassed\fR" 4
.IX Item "passed"
Run only the passed tests from last time. Useful to make sure that no new
problems have been introduced.
.ie n .IP """all""" 4
.el .IP "\f(CWall\fR" 4
.IX Item "all"
Run all tests in normal order. Multiple options may be specified, so to run
all tests with the failures from last time first:
.Sp
.Vb 1
\& pg_prove \-\-state failed,all,save
.Ve
.ie n .IP """hot""" 4
.el .IP "\f(CWhot\fR" 4
.IX Item "hot"
Run the tests that most recently failed first. The last failure time of each
test is stored. The \f(CW\*(C`hot\*(C'\fR option causes tests to be run in most\-recent\-
failure order.
.Sp
.Vb 1
\& pg_prove \-\-state hot,save
.Ve
.Sp
Tests that have never failed will not be selected. To run all tests with the
most recently failed first use
.Sp
.Vb 1
\& pg_prove \-\-state hot,all,save
.Ve
.Sp
This combination of options may also be specified thus
.Sp
.Vb 1
\& pg_prove \-\-state adrian
.Ve
.ie n .IP """todo""" 4
.el .IP "\f(CWtodo\fR" 4
.IX Item "todo"
Run any tests with todos.
.ie n .IP """slow""" 4
.el .IP "\f(CWslow\fR" 4
.IX Item "slow"
Run the tests in slowest to fastest order. This is useful in conjunction with
the \f(CW\*(C`\-j\*(C'\fR parallel testing switch to ensure that your slowest tests start
running first.
.Sp
.Vb 1
\& pg_prove \-\-state slow \-j9
.Ve
.ie n .IP """fast""" 4
.el .IP "\f(CWfast\fR" 4
.IX Item "fast"
Run test tests in fastest to slowest order.
.ie n .IP """new""" 4
.el .IP "\f(CWnew\fR" 4
.IX Item "new"
Run the tests in newest to oldest order based on the modification times of the
test scripts.
.ie n .IP """old""" 4
.el .IP "\f(CWold\fR" 4
.IX Item "old"
Run the tests in oldest to newest order.
.ie n .IP """fresh""" 4
.el .IP "\f(CWfresh\fR" 4
.IX Item "fresh"
Run those test scripts that have been modified since the last test run.
.ie n .IP """save""" 4
.el .IP "\f(CWsave\fR" 4
.IX Item "save"
Save the state on exit. The state is stored in a file called \fI.pg_prove\fR
(\fI_pg_prove\fR on Windows and \s-1VMS\s0) in the current directory.
.RE
.RS 4
.Sp
The \f(CW\*(C`\-\-state\*(C'\fR switch may be used more than once.
.Sp
.Vb 1
\& pg_prove \-\-state hot \-\-state all,save
.Ve
.RE
.SS "Display Options"
.IX Subsection "Display Options"
.ie n .IP """\-v""" 4
.el .IP "\f(CW\-v\fR" 4
.IX Item "-v"
.PD 0
.ie n .IP """\-\-verbose""" 4
.el .IP "\f(CW\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
.Vb 2
\& pg_prove \-\-verbose
\& pg_prove \-v
.Ve
.Sp
Display standard output of test scripts while running them. This behavior can
also be triggered by setting the \f(CW$TEST_VERBOSE\fR environment variable to a
true value.
.ie n .IP """\-f""" 4
.el .IP "\f(CW\-f\fR" 4
.IX Item "-f"
.PD 0
.ie n .IP """\-\-failures""" 4
.el .IP "\f(CW\-\-failures\fR" 4
.IX Item "--failures"
.PD
.Vb 2
\& pg_prove \-\-failures
\& pg_prove \-f
.Ve
.Sp
Show failed tests.
.ie n .IP """\-o""" 4
.el .IP "\f(CW\-o\fR" 4
.IX Item "-o"
.PD 0
.ie n .IP """\-\-comments""" 4
.el .IP "\f(CW\-\-comments\fR" 4
.IX Item "--comments"
.PD
Show comments, such as diagnostics output by \f(CW\*(C`diag()\*(C'\fR. Enabled by default.
use \f(CW\*(C`\-\-no\-comments\*(C'\fR to disable.
.ie n .IP """\-\-directives""" 4
.el .IP "\f(CW\-\-directives\fR" 4
.IX Item "--directives"
.Vb 1
\& pg_prove \-\-directives
.Ve
.Sp
Only show results with \s-1TODO\s0 or \s-1SKIP\s0 directives.
.ie n .IP """\-q""" 4
.el .IP "\f(CW\-q\fR" 4
.IX Item "-q"
.PD 0
.ie n .IP """\-\-quiet""" 4
.el .IP "\f(CW\-\-quiet\fR" 4
.IX Item "--quiet"
.PD
.Vb 2
\& pg_prove \-\-quiet
\& pg_prove \-q
.Ve
.Sp
Suppress some test output while running tests.
.ie n .IP """\-Q""" 4
.el .IP "\f(CW\-Q\fR" 4
.IX Item "-Q"
.PD 0
.ie n .IP """\-\-QUIET""" 4
.el .IP "\f(CW\-\-QUIET\fR" 4
.IX Item "--QUIET"
.PD
.Vb 2
\& pg_prove \-\-QUIET
\& pg_prove \-Q
.Ve
.Sp
Only print summary results.
.ie n .IP """\-\-parse""" 4
.el .IP "\f(CW\-\-parse\fR" 4
.IX Item "--parse"
.Vb 1
\& pg_prove \-\-parse
.Ve
.Sp
Enables the display of any \s-1TAP\s0 parsing errors as tests run. Useful for
debugging new \s-1TAP\s0 emitters.
.ie n .IP """\-\-normalize""" 4
.el .IP "\f(CW\-\-normalize\fR" 4
.IX Item "--normalize"
.Vb 1
\& pg_prove \-\-normalize
.Ve
.Sp
Normalize \s-1TAP\s0 output in verbose output. Errors in the harnessed \s-1TAP\s0 corrected
by the parser will be corrected.
.ie n .IP """\-\-dry""" 4
.el .IP "\f(CW\-\-dry\fR" 4
.IX Item "--dry"
.PD 0
.ie n .IP """\-D""" 4
.el .IP "\f(CW\-D\fR" 4
.IX Item "-D"
.PD
.Vb 2
\& pg_prove \-\-dry tests/
\& pg_prove \-D
.Ve
.Sp
Dry run. Just outputs a list of the tests that would have been run.
.ie n .IP """\-\-merge""" 4
.el .IP "\f(CW\-\-merge\fR" 4
.IX Item "--merge"
Merge test scripts' \f(CW\*(C`STDERR\*(C'\fR with their \f(CW\*(C`STDOUT\*(C'\fR. Not really relevant to
pgTAP tests, which only print to \f(CW\*(C`STDERR\*(C'\fR when an exception is thrown.
.ie n .IP """\-t""" 4
.el .IP "\f(CW\-t\fR" 4
.IX Item "-t"
.PD 0
.ie n .IP """\-\-timer""" 4
.el .IP "\f(CW\-\-timer\fR" 4
.IX Item "--timer"
.PD
.Vb 2
\& pg_prove \-\-timer
\& pg_prove \-t
.Ve
.Sp
Print elapsed time after each test file.
.ie n .IP """\-c""" 4
.el .IP "\f(CW\-c\fR" 4
.IX Item "-c"
.PD 0
.ie n .IP """\-\-color""" 4
.el .IP "\f(CW\-\-color\fR" 4
.IX Item "--color"
.PD
.Vb 2
\& pg_prove \-\-color
\& pg_prove \-c
.Ve
.Sp
Display test results in color. Colored test output is the default, but if
output is not to a terminal, color is disabled.
.Sp
Requires Term::ANSIColor on Unix-like platforms and
Win32::Console on Windows. If the necessary module is not
installed colored output will not be available.
.ie n .IP """\-\-nocolor""" 4
.el .IP "\f(CW\-\-nocolor\fR" 4
.IX Item "--nocolor"
Do not display test results in color.
.ie n .IP """\-\-shuffle""" 4
.el .IP "\f(CW\-\-shuffle\fR" 4
.IX Item "--shuffle"
.Vb 1
\& pg_prove \-\-shuffle tests/
.Ve
.Sp
Test scripts are normally run in alphabetical order. Use \f(CW\*(C`\-\-reverse\*(C'\fR to run
them in in random order. Not relevant when used with \f(CW\*(C`\-\-runtests\*(C'\fR.
.ie n .IP """\-\-reverse""" 4
.el .IP "\f(CW\-\-reverse\fR" 4
.IX Item "--reverse"
.Vb 1
\& pg_prove \-\-reverse tests/
.Ve
.Sp
Test scripts are normally run in alphabetical order. Use \f(CW\*(C`\-\-reverse\*(C'\fR to run
them in reverse order. Not relevant when used with \f(CW\*(C`\-\-runtests\*(C'\fR.
.ie n .IP """\-a""" 4
.el .IP "\f(CW\-a\fR" 4
.IX Item "-a"
.PD 0
.ie n .IP """\-\-archive""" 4
.el .IP "\f(CW\-\-archive\fR" 4
.IX Item "--archive"
.PD
.Vb 2
\& pg_prove \-\-archive tap.tar.gz
\& pg_prove \-a test_output.tar
.Ve
.Sp
Send the \s-1TAP\s0 output to a \s-1TAP\s0 archive file as well as to the normal output
destination. The archive formats supported are \fI.tar\fR and \fI.tar.gz\fR.
.ie n .IP """\-f""" 4
.el .IP "\f(CW\-f\fR" 4
.IX Item "-f"
.PD 0
.ie n .IP """\-\-formatter""" 4
.el .IP "\f(CW\-\-formatter\fR" 4
.IX Item "--formatter"
.PD
.Vb 2
\& pg_prove \-\-formatter TAP::Formatter::File
\& pg_prove \-f TAP::Formatter::Console
.Ve
.Sp
The name of the class to use to format output. The default is
TAP::Formatter::Console, or
TAP::Formatter::File if the output isn't a \s-1TTY.\s0
.ie n .IP """\-\-count""" 4
.el .IP "\f(CW\-\-count\fR" 4
.IX Item "--count"
.Vb 1
\& pg_prove \-\-count
.Ve
.Sp
Show the X/Y test count as tests run when not verbose (default).
.ie n .IP """\-\-nocount""" 4
.el .IP "\f(CW\-\-nocount\fR" 4
.IX Item "--nocount"
.Vb 1
\& pg_prove \-\-nocount
.Ve
.Sp
Disable the display of the X/Y test count as tests run.
.SS "Metadata Options"
.IX Subsection "Metadata Options"
.ie n .IP """\-H""" 4
.el .IP "\f(CW\-H\fR" 4
.IX Item "-H"
.PD 0
.ie n .IP """\-?""" 4
.el .IP "\f(CW\-?\fR" 4
.IX Item "-?"
.ie n .IP """\-\-help""" 4
.el .IP "\f(CW\-\-help\fR" 4
.IX Item "--help"
.PD
.Vb 2
\& pg_prove \-\-help
\& pg_prove \-H
.Ve
.Sp
Outputs a brief description of the options supported by \f(CW\*(C`pg_prove\*(C'\fR and exits.
.ie n .IP """\-m""" 4
.el .IP "\f(CW\-m\fR" 4
.IX Item "-m"
.PD 0
.ie n .IP """\-\-man""" 4
.el .IP "\f(CW\-\-man\fR" 4
.IX Item "--man"
.PD
.Vb 2
\& pg_prove \-\-man
\& pg_prove \-m
.Ve
.Sp
Outputs this documentation and exits.
.ie n .IP """\-V""" 4
.el .IP "\f(CW\-V\fR" 4
.IX Item "-V"
.PD 0
.ie n .IP """\-\-version""" 4
.el .IP "\f(CW\-\-version\fR" 4
.IX Item "--version"
.PD
.Vb 2
\& pg_prove \-\-version
\& pg_prove \-V
.Ve
.Sp
Outputs the program name and version and exits.
.SH "Author"
.IX Header "Author"
David E. Wheeler
.SH "Copyright"
.IX Header "Copyright"
Copyright (c) 2008\-2022 David E. Wheeler. Some Rights Reserved.