This file is indexed.

/usr/bin/pg_prove is in libtap-parser-sourcehandler-pgtap-perl 3.29-1.

This file is owned by root:root, with mode 0o755.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
#!/usr/bin/perl -w

eval 'exec /usr/bin/perl -w -S $0 ${1+"$@"}'
    if 0; # not running under some shell

use strict;
use App::Prove;
use Getopt::Long;

our $VERSION = '3.29';
$|++;

Getopt::Long::Configure(qw(no_ignore_case bundling pass_through));

my $opts = { color => 1, comments => 1 };

Getopt::Long::GetOptions(
    'psql-bin|b=s' => \$opts->{psql},
    'dbname|d=s'   => \$opts->{dbname},
    'username|U=s' => \$opts->{username},
    'host|h=s'     => \$opts->{host},
    'port|p=s'     => \$opts->{port},
    'pset|P=s%'    => \$opts->{pset},
    'set|S=s%'     => \$opts->{set},
    'runtests|R'   => \$opts->{runtests},
    'schema|s=s'   => \$opts->{schema},
    'match|x=s'    => \$opts->{match},
    'timer|t!'     => \$opts->{timer},
    'version|V'    => \$opts->{version},
    'ext=s@'       => \$opts->{ext},
    'comments|o!'  => \$opts->{comments},
    'help|H|?'     => \$opts->{help},
    'man|m'        => \$opts->{man},
) or require Pod::Usage && Pod::Usage::pod2usage(2);

if ($opts->{version}) {
    print 'pg_prove ', main->VERSION, $/;
    exit;
}

if ( $opts->{help} or $opts->{man} ) {
    require Pod::Usage;
    Pod::Usage::pod2usage(
        '-sections' => $opts->{man} ? '.+' : '(?i:(Usage|Options))',
        '-verbose'  => 99,
        '-exitval'  => 0,
    )
}

if ($opts->{version}) {
    print 'pg_prove ', main->VERSION, $/;
    exit;
}

my $prove_class = 'App::Prove';
my $runtests_call;

# --schema and --match assume --runtests.
if ($opts->{runtests} || $opts->{schema} || $opts->{match}) {
    # We're just going to call `runtests()`.
    $prove_class .= '::pgTAP';
    my @args;
    for my $key (qw(schema match)) {
        next unless $opts->{$key};
        (my $arg = $opts->{$key}) =~ s/'/\\'/g;
        # Gotta cast the arguments.
        push @args, "'$arg'::" . ($key eq 'schema' ? 'name' : 'text');
    }

    $runtests_call = 'runtests(' . join( ', ', @args ) . ');'
}

my $app = $prove_class->new;
$app->process_args(
    @ARGV,
    (map { ('--ext' => $_) } @{ $opts->{ext} || ['.pg'] }),
    qw(--source pgTAP),
    ($opts->{comments} ? ('--comments') : ()),
    ($opts->{timer} ? ('--timer') : ()),
    (map {
        ('--pgtap-option' => "$_=$opts->{$_}")
    } grep {
        $opts->{$_}
    } qw(psql dbname username host port)),
    (map {
        ('--pgtap-option' => "pset=$_=$opts->{pset}{$_}")
    } keys %{ $opts->{pset} }),
    (map {
        ('--pgtap-option' => "set=$_=$opts->{set}{$_}")
    } keys %{ $opts->{set} })
);

exit($app->run ? 0 : 1);

PGPROVE: {
    package # Hide from indexer.
        App::Prove::pgTAP;
    use base 'App::Prove';
    sub _get_tests {
        return [
            "pgsql: SELECT * FROM $runtests_call",
            $runtests_call,
        ]
    }
}

__END__

=encoding utf8

=head1 Name

pg_prove - A command-line tool for running and harnessing pgTAP tests

=head1 Usage

  pg_prove tests/
  pg_prove --dbname template1 test*.sql
  pg_prove -d testdb --runtests

=head1 Description

C<pg_prove> is a command-line application to run one or more
L<pgTAP|http://pgtap.org/> tests in a PostgreSQL database. The output of the
tests is harvested and processed by L<TAP::Harness|TAP::Harness> in order to
summarize the results of the test.

Tests can be written and run in one of two ways, as SQL scripts or as
xUnit-style database functions.

=head2 Test Scripts

pgTAP test scripts should consist of a series of SQL statements that output
TAP. Here’s a simple example that assumes that the pgTAP functions have been
installed in the database:

    -- Start transaction and plan the tests.
    BEGIN;
    SELECT plan(1);

    -- Run the tests.
    SELECT pass( 'My test passed, w00t!' );

    -- Finish the tests and clean up.
    SELECT * FROM finish();
    ROLLBACK;

Now run the tests by passing the list of SQL script names or the name of a
test directory to C<pg_prove>. Here’s what it looks like when the pgTAP tests
are run with C<pg_prove>

    % 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

=head2 xUnit Test Functions

pgTAP test functions should return a set of text, and then simply return the
values returned by pgTAP functions, like so:

    CREATE OR REPLACE FUNCTION setup_insert(
    ) RETURNS SETOF TEXT AS $$
        RETURN NEXT is( MAX(nick), NULL, 'Should have no users') FROM users;
        INSERT INTO users (nick) VALUES ('theory');
    $$ LANGUAGE plpgsql;

    Create OR REPLACE FUNCTION test_user(
    ) RETURNS SETOF TEXT AS $$
        SELECT is( nick, 'theory', 'Should have nick') FROM users;
    END;
    $$ LANGUAGE sql;

Once you have these functions defined in your database, you can run them with
C<pg_prove> by using the C<--runtests> option.

    % 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

Be sure to pass the C<--schema> option if your test functions are all in one
schema, and the C<--match> option if they have names that don’t start with
“test”. For example, if you have all of your test functions in the “test”
schema and I<ending> with “test,” run the tests like so:

    pg_prove --dbname mydb --schema test --match 'test$'

=head1 Options

 -b   --psql-bin PSQL        Location of the C<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 C<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 F<.pg>)
 -r,  --recurse              Recursively descend into directories.
      --ignore-exit          Ignore exit status from test scripts.
      --trap                 Trap C<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't process default F<.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' C<STDERR> and C<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.

=head1 Options Details

=head2 Database Options

=over

=item C<-b>

=item C<--psql-bin>

  pg_prove --psql-bin /usr/local/pgsql/bin/psql
  pg_prove -b /usr/local/bin/psql

Path to the C<psql> program, which will be used to actually run the tests.
Defaults to F<psql>, which should work well, when it is in your path.

=item C<-d>

=item C<--dbname>

  pg_prove --dbname try
  pg_prove -d postgres

The name of database to which to connect. Defaults to the value of the
C<$PGDATABASE> environment variable or to the system username.

=item C<-U>

=item C<--username>

  pg_prove --username foo
  pg_prove -U postgres

PostgreSQL user name to connect as. Defaults to the value of the C<$PGUSER>
environment variable or to the operating system name of the user running the
application.

=item C<-h>

=item C<--host>

  pg_prove --host pg.example.com
  pg_prove -h dev.local

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 C<$PGHOST> environment variable or
localhost.

=item C<-p>

=item C<--port>

  pg_prove --port 1234
  pg_prove -p 666

Specifies the TCP port or the local Unix-domain socket file extension on which
the server is listening for connections. Defaults to the value of the
C<$PGPORT> environment variable or, if not set, to the port specified at
compile time, usually 5432.

=item C<-P>

=item C<--pset>

  pg_prove --pset tuples_only=0
  pg_prove -P null=[NULL]

Specifies printing options in the style of C<\pset> in the C<psql> program.
See L<http://www.postgresql.org/docs/current/static/app-psql.html> for details
on the supported options.

=item C<-S>

=item C<--set>

  pg_prove --set MY_CONTRACT=321
  pg_prove -S TEST_SEARCH_PATH=test,public

Sets local variables for psql in the style of C<\set> in the C<psql> program.
See L<http://www.postgresql.org/docs/current/static/app-psql.html> for details
on the supported options.

=item C<--runtests>

  pg_prove --runtests
  pg_prove -r

Don’t run any test scripts, but just use the C<runtests()> 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, C<pg_prove> tells C<psql>
to run something like:

  psql --command 'SELECT * FROM runtests()'

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.

=item C<-s>

=item C<--schema>

  pg_prove --schema test
  pg_prove -s mytest

Used with C<--runtests>, and, in fact, implicitly forces C<--runtests> 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 C<psql> to run something like:

  psql --command "SELECT * FROM runtests('test'::name)"

=item C<-x>

=item C<--match>

  pg_prove --match 'test$'
  pg_prove -x _test_

Used with C<--runtests>, and, in fact, implicitly forces C<--runtests> to be
true. This option can be used to specify a POSIX regular expression that will
be used to search for xUnit functions to run. Basically, it tells C<psql> to
run something like:

  psql --command "SELECT * FROM runtests('_test_'::text)"

This will run any visible functions with the string “_test_” in their names.
This can be especially useful if you just want to run a single test in a
given schema. For example, this:

  pg_prove --schema testing --match '^test_widgets$'

Will have C<psql> execute the C<runtests()> function like so:

 SELECT * FROM runtests('testing'::name, '^test_widgets$'::text);

=back

=head2 Behavioral Options

=over

=item C<--ext>

  pg_prove --ext .sql tests/

Set the extension for test files (default F<.pg>). May be specified multiple
times if you have test scripts with multiple extensions:

  pg_prove --ext .sql --ext .pg --ext .pgt

=item C<-r>

=item C<--recurse>

  pg_prove --recurse tests/
  pg_prove --recurse sql/

Recursively descend into directories when searching for tests. Not relevant
with C<--runtests>.

=item C<--ignore-exit>

  pg_prove --ignore-exit

Ignore exit status from test scripts. Normally if a script triggers a database
exception, C<psql> will exit with an error code and, even if all tests passed,
the test will be considered a failure. Use C<--ignore-exit> to ignore such
situations (at your own peril).

=item C<--trap>

  pg_prove --trap

Trap C<Ctrl-C> and print a summary on interrupt.

=item C<--harness>

  pg_prove --harness TAP::Harness::Color

Specify a subclass of L<TAP::Harness> to use for the test harness. Defaults to
TAP::Harness (unless C<--archive> is specified, in which case it uses
L<TAP::Harness::Archive>).

=item C<-j>

=item C<-jobs>

Run N test jobs in parallel (try 9.)

=item C<--rc>

  pg_prove --rc pg_prove.rc

Process options from the specified configuration file.

If C<--rc> is not specified and F<./.proverc> or F<~/.proverc> exist, they
will be read and any options they contain processed before the command line
options. Options in configuration files are specified in the same way as
command line options:

           # .proverc
           --state=hot,fast,save
           -j9

Under Windows and VMS the option file is named F<_proverc> rather than
F<.proverc> and is sought only in the current directory.

=item C<--norc>

Do not process F<./.proverc> or F<~/.proverc>.

=item C<--state>

You can ask C<pg_prove> to remember the state of previous test runs and select
and/or order the tests to be run based on that saved state.

The C<--state> switch requires an argument which must be a comma separated
list of one or more of the following options.

=over

=item C<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.

    # Run all tests in random order
    pg_prove --state save --shuffle

    # Run them again in the same order
    pg_prove --state last

=item C<failed>

Run only the tests that failed on the last run.

    # Run all tests
    pg_prove --state save

    # Run failures
    pg_prove --state failed

If you also specify the C<save> option newly passing tests will be
excluded from subsequent runs.

    # Repeat until no more failures
    pg_prove --state failed,save

=item C<passed>

Run only the passed tests from last time. Useful to make sure that no new
problems have been introduced.

=item C<all>

Run all tests in normal order. Multiple options may be specified, so to run
all tests with the failures from last time first:

    pg_prove --state failed,all,save

=item C<hot>

Run the tests that most recently failed first. The last failure time of each
test is stored. The C<hot> option causes tests to be run in most-recent-
failure order.

    pg_prove --state hot,save

Tests that have never failed will not be selected. To run all tests with the
most recently failed first use

    pg_prove --state hot,all,save

This combination of options may also be specified thus

    pg_prove --state adrian

=item C<todo>

Run any tests with todos.

=item C<slow>

Run the tests in slowest to fastest order. This is useful in conjunction with
the C<-j> parallel testing switch to ensure that your slowest tests start
running first.

    pg_prove --state slow -j9

=item C<fast>

Run test tests in fastest to slowest order.

=item C<new>

Run the tests in newest to oldest order based on the modification times of the
test scripts.

=item C<old>

Run the tests in oldest to newest order.

=item C<fresh>

Run those test scripts that have been modified since the last test run.

=item C<save>

Save the state on exit. The state is stored in a file called F<.pg_prove>
(F<_pg_prove> on Windows and VMS) in the current directory.

=back

The C<--state> switch may be used more than once.

    pg_prove --state hot --state all,save

=back

=head2 Display Options

=over

=item C<-v>

=item C<--verbose>

  pg_prove --verbose
  pg_prove -v

Display standard output of test scripts while running them. This behavior can
also be triggered by setting the C<$TEST_VERBOSE> environment variable to a
true value.

=item C<-f>

=item C<--failures>

  pg_prove --failures
  pg_prove -f

Show failed tests.

=item C<-o>

=item C<--comments>

Show comments, such as diagnostics output by C<diag()>. Enabled by default.
use C<--no-comments> to disable.

=item C<--directives>

  pg_prove --directives

Only show results with TODO or SKIP directives.

=item C<-q>

=item C<--quiet>

  pg_prove --quiet
  pg_prove -q

Suppress some test output while running tests.

=item C<-Q>

=item C<--QUIET>

  pg_prove --QUIET
  pg_prove -Q

Only print summary results.

=item C<--parse>

  pg_prove --parse

Enables the display of any TAP parsing errors as tests run. Useful for
debugging new TAP emitters.

=item C<--normalize>

  pg_prove --normalize

Normalize TAP output in verbose output. Errors in the harnessed TAP corrected
by the parser will be corrected.

=item C<--dry>

=item C<-D>

  pg_prove --dry tests/
  pg_prove -D

Dry run. Just outputs a list of the tests that would have been run.

=item C<--merge>

Merge test scripts' C<STDERR> with their C<STDOUT>. Not really relevant to
pgTAP tests, which only print to C<STDERR> when an exception is thrown.

=item C<-t>

=item C<--timer>

  pg_prove --timer
  pg_prove -t

Print elapsed time after each test file.

=item C<-c>

=item C<--color>

  pg_prove --color
  pg_prove -c

Display test results in color. Colored test output is the default, but if
output is not to a terminal, color is disabled.

Requires L<Term::ANSIColor|Term::ANSIColor> on Unix-like platforms and
L<Win32::Console|Win32::Console> on Windows. If the necessary module is not
installed colored output will not be available.

=item C<--nocolor>

Do not display test results in color.

=item C<--shuffle>

  pg_prove --shuffle tests/

Test scripts are normally run in alphabetical order. Use C<--reverse> to run
them in in random order. Not relevant when used with C<--runtests>.

=item C<--reverse>

  pg_prove --reverse tests/

Test scripts are normally run in alphabetical order. Use C<--reverse> to run
them in reverse order. Not relevant when used with C<--runtests>.

=item C<-a>

=item C<--archive>

  pg_prove --archive tap.tar.gz
  pg_prove -a test_output.tar

=item C<-f>

=item C<--formatter>

  pg_prove --formatter TAP::Formatter::File
  pg_prove -f TAP::Formatter::Console

The name of the class to use to format output. The default is
L<TAP::Formatter::Console|TAP::Formatter::Console>, or
L<TAP::Formatter::File|TAP::Formatter::File> if the output isn't a TTY.

=item C<--count>

  pg_prove --count

Show the X/Y test count as tests run when not verbose (default).

=item C<--nocount>

  pg_prove --nocount

Disable the display of the X/Y test count as tests run.

Send the TAP output to a TAP archive file as well as to the normal output
destination. The archive formats supported are F<.tar> and F<.tar.gz>.

=back

=head2 Metadata Options

=over

=item C<-H>

=item C<-?>

=item C<--help>

  pg_prove --help
  pg_prove -H

Outputs a brief description of the options supported by C<pg_prove> and exits.

=item C<-m>

=item C<--man>

  pg_prove --man
  pg_prove -m

Outputs this documentation and exits.

=item C<-V>

=item C<--version>

  pg_prove --version
  pg_prove -V

Outputs the program name and version and exits.

=back

=head1 Author

David E. Wheeler <dwheeler@cpan.org>

=head1 Copyright

Copyright (c) 2008-2012 David E. Wheeler. Some Rights Reserved.

=cut