Test::Database(3) User Contributed Perl Documentation Test::Database(3)NAMETest::Database - Database handles ready for testing
SYNOPSIS
Maybe you wrote generic code you want to test on all available
databases:
use Test::More;
use Test::Database;
# get all available handles
my @handles = Test::Database->handles();
# plan the tests
plan tests => 3 + 4 * @handles;
# run the tests
for my $handle (@handles) {
diag "Testing with " . $handle->dbd(); # mysql, SQLite, etc.
# there are several ways to access the dbh:
# let $handle do the connect()
my $dbh = $handle->dbh();
# do the connect() yourself
my $dbh = DBI->connect( $handle->connection_info() );
my $dbh = DBI->connect( $handle->dsn(), $handle->username(),
$handle->password() );
}
It's possible to limit the results, based on the databases your code
supports:
my @handles = Test::Database->handles(
'SQLite', # SQLite database
{ dbd => 'mysql' }, # or mysql database
{ driver => 'Pg' }, # or Postgres database
);
# use them as above
If you only need a single database handle, all the following return the
same one:
my $handle = ( Test::Database->handles(@requests) )[0];
my ($handle) = Test::Database->handles(@requests);
my $handle = Test::Database->handles(@requests); # scalar context
my $handle = Test::Database->handle(@requests); # singular!
my @handles = Test::Database->handle(@requests); # one or zero item
You can use the same requests again if you need to use the same test
databases over several test scripts.
DESCRIPTION
Quoting Michael Schwern:
There's plenty of modules which need a database, and they all have to
be configured differently and they're always a PITA when you first
install and each and every time they upgrade.
User setup can be dealt with by making Test::Database a build
dependency. As part of Test::Database's install process it walks the
user through the configuration process. Once it's done, it writes out a
config file and then it's done for good.
See <http://www.nntp.perl.org/group/perl.qa/2008/10/msg11645.html> for
the thread that led to the creation of "Test::Database".
"Test::Database" provides a simple way for test authors to request a
test database, without worrying about environment variables or the test
host configuration.
See SYNOPSIS for typical usage.
METHODS
"Test::Database" provides the following methods:
list_drivers( [$type] )
Return a list of driver names of the given "type".
"all" returns the list of all existing "Test::Database::Driver"
subclasses.
"available" returns the list of "Test::Database::Driver" subclasses
for which the matching "DBD" class is available.
Called with no parameter (or anything not matching "all" or
"available"), it will return the list of currently loaded drivers.
drivers()
Returns the "Test::Database::Driver" instances that are setup by
"load_drivers()" and updated by "load_config()".
load_drivers()
Load the available drivers from the system (file-based drivers,
usually).
load_config( @files )
Read configuration from the files in @files.
If no file is provided, the local equivalent of ~/.test-database is
used.
clean_config()
Empties whatever configuration has already been loaded. Also
removes the loaded drivers list.
handles( @requests )
Return a set of "Test::Database::Handle" objects that match the
given @requests.
If @requests is not provided, return all the available handles.
See REQUESTS for details about writing requests.
handle( @request )
Singular version of "handles()", that returns the first matching
handle.
REQUESTS
The "handles()" method takes requests as parameters. A request is a
simple hash reference, with a number of recognized keys.
· "dbd": driver name (based on the "DBD::" name).
"driver" is an alias for "dbd". If the two keys are present, the
"driver" key will be ignored.
If missing, all available drivers will match.
· "version": exact database engine version
Only database engines having a version string identical to the
given version string will match.
· "min_version": minimum database engine version
Only database engines having a version number greater or equal to
the given minimum version will match.
· "max_version": maximum database engine version
Only database engines having a version number lower (and not equal)
to the given maximum version will match.
· "regex_version": matching database engine version
Only database engines having a version string that matches the
given regular expression will match.
A request can also consist of a single string, in which case it is
interpreted as a shortcut for "{ dbd =" $string }>.
FILES
The list of available, authorized DSN is stored in the local equivalent
of ~/.test-database. It's a simple list of key/value pairs, with the
"dsn", "driver_dsn" or "key" keys being used to split successive
entries:
# mysql
dsn = dbi:mysql:database=mydb;host=localhost;port=1234
username = user
password = s3k r3t
# Oracle
dsn = dbi:Oracle:test
# set a unique key when creating databases
key = thwapp
# a "driver" with full access (create/drop databases)
driver_dsn = dbi:mysql:
username = root
The "username" and "password" keys are optional and empty strings will
be used if they are not provided.
Empty lines and comments are ignored.
Optionaly, the "key" section is used to add a "unique" element to the
databases created by the drivers (as defined by "driver_dsn"). It
allows several hosts to share access to the same database server
without risking a race condition when creating a new database. See
Test::Database::Tutorial for a longer explanation.
Individual drivers may accept extra parameters. See their documetation
for details. Unrecognized parameters and not used, and therefore
ignored.
AUTHOR
Philippe Bruhat (BooK), "<book@cpan.org>"
BUGS
Please report any bugs or feature requests to "bug-test-database at
rt.cpan.org", or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Database
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Database>. I will
be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Test::Database
You can also look for information at:
· RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Database
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Database>
· AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Database
<http://annocpan.org/dist/Test-Database>
· CPAN Ratings
http://cpanratings.perl.org/d/Test-Database
<http://cpanratings.perl.org/d/Test-Database>
· Search CPAN
http://search.cpan.org/dist/Test-Database
<http://search.cpan.org/dist/Test-Database>
TODO
Some of the items on the TODO list:
· Add a database engine autodetection script/module, to automatically
write the .test-database configuration file.
ACKNOWLEDGEMENTS
Thanks to "<perl-qa@perl.org>" for early comments.
Thanks to Nelson Ferraz for writing "DBIx::Slice", the testing of which
made me want to have a generic way to obtain a test database.
Thanks to Mark Lawrence for discussing this module with me, and sending
me an alternative implementation to show me what he needed.
Thanks to Kristian Koehntopp for helping me write a mysql driver, and
to Greg Sabino Mullane for writing a full Postgres driver, none of
which made it into the final release because of the complete change in
goals and implementation between versions 0.02 and 0.03.
The work leading to the new implementation (version 0.99 and later) was
carried on during the Perl QA Hackathon, held in Birmingham in March
2009. Thanks to Birmingham.pm for organizing it and to Booking.com for
sending me there.
Thanks to the early adopters: Alexis Sukrieh (SUKRIA), Nicholas Bamber
(SILASMONK) and Adam Kennedy (ADAMK).
COPYRIGHT
Copyright 2008-2010 Philippe Bruhat (BooK), all rights reserved.
LICENSE
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2011-07-20 Test::Database(3)
