TAP::Parser::SourceHandler::pgTAP - Stream TAP from pgTAP test scripts
In Build.PL for your application with pgTAP tests in t/*.pg:
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 using prove:
prove
prove --source Perl \ --ext .t --ext .pg \ --source pgTAP --pgtap-option dbname=try \ --pgtap-option username=postgres \ --pgtap-option suffix=.pg
If you have only pgTAP tests, just use pg_prove:
pg_prove
pg_prove --dbname try --username postgres
Direct use:
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 );
This source handler executes pgTAP tests. It does two things:
Looks at the TAP::Parser::Source passed to it to determine whether or not the source in question is in fact a pgTAP test ("can_handle").
Creates an iterator that will call psql to run the pgTAP tests ("make_iterator").
psql
Unless you're writing a plugin or subclassing TAP::Parser, you probably won't need to use this module directly.
If you just want to write tests with pgTAP, here's how:
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 for a comprehensive list of test functions.
search_path
Run your tests with prove like so:
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.
use_tap_harness
tap_harness_args
make_iterator()
pgTAP
sources
And that's it. Now get testing!
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 the "suffix" config 1 if its suffix is ".pg" 0.8 if its suffix is ".sql" 0.75 if its suffix is ".s"
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.
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.
$source->raw
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:
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.
$PGDATABASE
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.
$PGUSER
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.
$PGPORT
pset
Specifies a hash of printing options in the style of \pset in the psql program. See the psql documentation for details on the supported options.
\pset
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
This module is managed in an open GitHub repository. Feel free to fork and contribute, or to clone git://github.com/theory/tap-parser-sourcehandler-pgtap.git and send patches!
git://github.com/theory/tap-parser-sourcehandler-pgtap.git
Found a bug? Please post or email a report!
David E. Wheeler <dwheeler@cpan.org>
Copyright (c) 2010-2012 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.
To install TAP::Parser::SourceHandler::pgTAP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TAP::Parser::SourceHandler::pgTAP
CPAN shell
perl -MCPAN -e shell install TAP::Parser::SourceHandler::pgTAP
For more information on module installation, please visit the detailed CPAN module installation guide.