.\" 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 <https://pgtap.org/> 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 <https://www.postgresql.org/docs/current/app-psql.html>
to run the tests, and therefor supports all of the
environment variables <https://www.postgresql.org/docs/current/libpq-envars.html>,
as well as the password file <https://www.postgresql.org/docs/current/libpq-pgpass.html>
and service file <https://www.postgresql.org/docs/current/libpq-pgservice.html> 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 <https://www.postgresql.org/docs/current/static/app\-psql.html> 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 <https://www.postgresql.org/docs/current/static/app\-psql.html> 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, <pg_prove> does
support all of the usual libpq
Environment Variables <https://www.postgresql.org/docs/current/static/libpq-envars.html>.
.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 <dwheeler@cpan.org>
.SH "Copyright"
.IX Header "Copyright"
Copyright (c) 2008\-2022 David E. Wheeler. Some Rights Reserved.