Name¶
TAP::Parser::SourceHandler::pgTAP - Stream TAP from pgTAP test scripts
Synopsis¶
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 --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 --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 );
Description¶
This source handler executes pgTAP tests. It does two things:
- 1.
- 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").
- 2.
- Creates an iterator that will call "psql" to run
the pgTAP tests ("make_iterator").
Unless you're writing a plugin or subclassing TAP::Parser, you probably won't
need to use this module directly.
Testing with pgTAP¶
If you just want to write tests with pgTAP <
http://pgtap.org/>, 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 <http://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 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.
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
<http://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 <http://pgtap.org/>
Support¶
This module is managed in an open GitHub repository
<
http://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
<
http://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 and License¶
Copyright (c) 2010-2011 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.