/ 
Test-Database-0.99_01
River stage two • 11 direct dependents • 30 total dependents
/ Test::Database

NAME

Test::Database - Database handles ready for testing

SYNOPSIS

Maybe you need a test database for a specific database driver:

use Test::Database;

# connection information
my ( $dsn, $username, $password )
    = Test::Database->connection_info('SQLite');

# database handle
my $dbh = Test::Database->dbh('SQLite');

Maybe you want to use the same test database over several test scripts:

use Test::Database;

# connection information
my ( $dsn, $username, $password )
    = Test::Database->connection_info( SQLite => 'mydb' );

# database handle
my $dbh = Test::Database->dbh( SQLite => 'mydb' );

Maybe you wrote generic code you want to test on all available databases:

use Test::Database;

my @drivers = Test::Database->drivers();

for my $driver (@drivers) {
    my $handle = Test::Database->handle( $driver );
}

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.

Typical usage if the module require a specific database:

use Test::More;
use Test::Database;

my $dbh = Test::Database->dbh( SQLite => 'test' );
plan skip_all => 'No test SQLite database available' if !$dbh;

# rest of the test script

Typical usage if the module wants to run the test on as many databases as possible:

use Test::More;
use Test::Database;

for my $handle ( map { Test::Database->handle( $_ => 'test' ) }
    Test::Database->drivers() )
{
    diag 'Testing on ' . $handle->driver();
    my $dbh = $handle->dbh();

    # rest of the test script
}

METHODS

Test::Database provides the following methods:

all_drivers()

Return the list of supported drivers.

available_drivers()

Return the list of supported DBI drivers that are installed.

This is the intersection of the results of Test::Database->all_drivers() and DBI->available_drivers().

load_drivers( [ $file ] )

Read the database drivers configuration from the given $file and load them.

If $file is not given, the local equivalent of ~/.test-database is used.

save_drivers( [ $file ] )

Saver the available database drivers configuration to the given $file.

If $file is not given, the local equivalent of ~/.test-database is used.

unload_drivers()

Unload all drivers.

drivers( @requests )

Return the Test::Database::Driver objects corresponding to all the available drivers.

If @requests is provided, only the drivers that match one of the requests are returned.

See REQUESTS for details about writing requests.

handles( @requests )

Return a set of Test::Database::Handle objects that matche the given @requests.

If @requests is not provided, return a handle for each database that exists in each driver.

See REQUESTS for details about writing requests.

cleanup()

Call the cleanup() method of all available drivers.

REQUESTS

The drivers(), handles() and dbh() methods tales requests as parameters. A request is a simple hash reference, with a number of recognized keys.

Some keys have an effect on driver selection:

  • driver: driver name

    If missing, all available drivers will match.

  • min_version: minimum database engine version

    Only database engines having at least the given minimum version will match.

  • max_version: maximum database engine version

    Only database engines having at least the given maximum version will match.

Others have an effect on actual database selection:

  • name: name of the database to select or create.

    If a database of the given name exists in the select database engine, a handle to it will be returned.

    If the field is missing, a new database will be created with an automatically generated name.

  • keep: boolean

    By default, database are dropped at the end of the program's life. If this parameter is true, the database will not be dropped, and can be selected again using its name.

A request can also consist of a single string, in which case it is interpreted as a shortcut for { driver = $string }>.

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. 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:

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 implemenation 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 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.

COPYRIGHT

Copyright 2008-2009 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.