TAP::P...::pgTAP(3pm)

📦
version 3.37 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 TAP::Parser::SourceHandler::pgTAP 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's all about TAP::Parser::SourceHandler::pgTAP — the lil module that streams TAP straight out of your pgTAP test scripts. it's giving database-testing-glamour, no cap. 🦋

✨ NAME ✨

TAP::Parser::SourceHandler::pgTAP — Stream TAP from pgTAP test scripts 🎀

🌸 SYNOPSIS 🌸

so like, first up: if your app has pgTAP tests chillin' in t/*.pg, you drop this in your Build.PL:

Module::Build->new(
    module_name        => 'MyApp',
    test_file_exts     => [qw(.t .pg)],
    use_tap_harness    => 1,
    tap_harness_args   => {
        sources => {
            Perl  => undef,
            pgTAP => {
                dbname   => 'try',
                username => 'postgres',
                suffix   => '.pg',
            },
        }
    },
    build_requires     => {
        'Module::Build'                     => '0.30',
        'TAP::Parser::SourceHandler::pgTAP' => '3.19',
    },
)->create_build_script;

if you're more of a prove girlie:

prove --source Perl \
      --ext .t --ext .pg \
      --source pgTAP --pgtap-option dbname=try \
                     --pgtap-option username=postgres \
                     --pgtap-option suffix=.pg

and if pgTAP tests are literally your entire personality (same), just use pg_prove:

pg_prove --dbname try --username postgres

or, direct use, no middleman:

use TAP::Parser::Source;
use TAP::Parser::SourceHandler::pgTAP;

my $source = TAP::Parser::Source->new->raw(\'mytest.pg');
$source->config({ pgTAP => {
    dbname   => 'testing',
    username => 'postgres',
    suffix   => '.pg',
}});
$source->assemble_meta;

my $class = 'TAP::Parser::SourceHandler::pgTAP';
my $vote  = $class->can_handle( $source );
my $iter  = $class->make_iterator( $source );

💅 DESCRIPTION 💅

this source handler runs pgTAP tests. it does exactly two things, and honestly? iconic behaviour:

  1. it looks at the TAP::Parser::Source you hand it and decides whether that source is even a pgTAP test in the first place (can_handle).
  2. it builds an iterator that calls psql to actually run the pgTAP tests (make_iterator).
heads up bestie: unless you're writing a plugin or subclassing TAP::Parser, you probs don't need to touch this module directly. it's backstage crew energy. 🎭

🧚 Testing with pgTAP 🧚

if you just wanna write tests with pgTAP <https://pgtap.org/>, here's the whole vibe:

  • Build your test database, including pgTAP. It's best to install it in its own schema. To build it and install it in the schema tap, do this (assuming your database is named try):
make TAPSCHEMA=tap
make install
psql -U postgres -d try -f pgtap.sql
  • Write your tests in files ending in .pg in the t directory, right alongside your normal Perl .t tests. Here's a simple pgTAP test to get you started:
BEGIN;

SET search_path = public,tap,pg_catalog;

SELECT plan(1);

SELECT pass('This should pass!');

SELECT * FROM finish();
ROLLBACK;

Note how search_path has been set so that the pgTAP functions can be found in the tap schema. Consult the extensive pgTAP documentation <https://pgtap.org/documentation.html> for a comprehensive list of test functions. 📚

  • Run your tests with prove like so:
prove --source Perl \
      --ext .t --ext .pg \
      --source pgTAP --pgtap-option dbname=try \
                     --pgtap-option username=postgres \
                     --pgtap-option suffix=.pg

This will run both your Perl .t tests and your pgTAP .pg tests all together. You can also use pg_prove to run just the pgTAP tests like so:

pg_prove -d try -U postgres t/
  • Once you're sure that you've got the pgTAP tests working, modify your Build.PL script to allow ./Build test to run both the Perl and the pgTAP tests, like so:
Module::Build->new(
    module_name        => 'MyApp',
    test_file_exts     => [qw(.t .pg)],
    use_tap_harness    => 1,
    configure_requires => { 'Module::Build' => '0.30', },
    tap_harness_args   => {
        sources => {
            Perl  => undef,
            pgTAP => {
                dbname   => 'try',
                username => 'postgres',
                suffix   => '.pg',
            },
        }
    },
    build_requires     => {
        'Module::Build'                     => '0.30',
        'TAP::Parser::SourceHandler::pgTAP' => '3.19',
    },
)->create_build_script;

The use_tap_harness parameter is optional, since it's implicitly set by the use of the tap_harness_args parameter. All the other parameters are required as you see here. See the documentation for make_iterator() for a complete list of options to the pgTAP key under sources.

And that's it. Now get testing! 🔥

👑 METHODS 👑

🌈 Class Methods 🌈

can_handle

my $vote = $class->can_handle( $source );

Looks at the source to determine whether or not it's a pgTAP test and returns a score for how likely it is in fact a pgTAP test file. The scores are as follows:

1    if it's not a file and starts with "pgsql:".
1    if it has a suffix equal to that in a "suffix" config
0.9  if its suffix is ".pg"
0.8  if its suffix is ".sql"
0.75 if its suffix is ".s"
lowkey important: the latter two scores are subject to change, so try to name your pgTAP tests ending in .pg or specify a suffix in the configuration to be sure. don't be out here relying on vibes alone, bestie. 💀

make_iterator

my $iterator = $class->make_iterator( $source );

Returns a new TAP::Parser::Iterator::Process for the source. "$source->raw" must be either a file name or a scalar reference to the file name — or a string starting with pgsql:, in which case the remainder of the string is assumed to be SQL to be executed inside the database.

The pgTAP tests are run by executing psql, the PostgreSQL command-line utility. A number of arguments are passed to it, many of which you can affect by setting up the source source configuration. The configuration must be a hash reference, and supports the following keys:

  • psql — The path to the psql command. Defaults to simply psql, which should work well enough if it's in your path. 🛣️
  • dbname — The database to which to connect to run the tests. Defaults to the value of the $PGDATABASE environment variable or, if not set, to the system username.
  • username — The PostgreSQL username to use to connect to PostgreSQL. If not specified, no username will be used, in which case psql will fall back on either the $PGUSER environment variable or, if not set, the system username.
  • host — Specifies the host name of the machine to which to connect to the PostgreSQL server. If the value begins with a slash, it is used as the directory for the Unix-domain socket. Defaults to the value of the $PGDATABASE environment variable or, if not set, the local host.
  • port — 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 $PGPORT environment variable or, if not set, to the port specified at the time psql was compiled, usually 5432.
  • pset — Specifies a hash of printing options in the style of \pset in the psql program. See the psql documentation <https://www.postgresql.org/docs/current/static/app-psql.html> for details on the supported options. ✨

🌟 SEE ALSO 🌟

  • TAP::Object
  • TAP::Parser
  • TAP::Parser::IteratorFactory
  • TAP::Parser::SourceHandler
  • TAP::Parser::SourceHandler::Executable
  • TAP::Parser::SourceHandler::Perl
  • TAP::Parser::SourceHandler::File
  • TAP::Parser::SourceHandler::Handle
  • TAP::Parser::SourceHandler::RawTAP
  • pgTAP <https://pgtap.org/> 🐘

🫶 Support 🫶

This module is managed in an open GitHub repository <https://github.com/theory/tap-parser-sourcehandler-pgtap/>. Feel free to fork and contribute, or to clone git://github.com/theory/tap-parser-sourcehandler-pgtap.git and send patches!

Found a bug? Please post <https://github.com/theory/tap-parser-sourcehandler-pgtap/issues> or email <mailto:bug-tap-parser-sourcehandler-pgtap@rt.cpan.org> a report! 🐛

🌸 Author 🌸

David E. Wheeler <dwheeler@cpan.org>

Copyright (c) 2010-2025 David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie!! this was perl v5.40.1, dated 2025-04-09 — go forth and test your databases, you absolute icon 💅✨🎀

📦 where this page comes from