.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::Database 3pm" .TH Test::Database 3pm "2015-12-23" "perl v5.22.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Database \- Database handles ready for testing .SH "SYNOPSIS" .IX Header "SYNOPSIS" Maybe you wrote generic code you want to test on all available databases: .PP .Vb 2 \& 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() ); \& } .Ve .PP It's possible to limit the results, based on the databases your code supports: .PP .Vb 5 \& my @handles = Test::Database\->handles( \& \*(AqSQLite\*(Aq, # SQLite database \& { dbd => \*(Aqmysql\*(Aq }, # or mysql database \& { driver => \*(AqPg\*(Aq }, # or Postgres database \& ); \& \& # use them as above .Ve .PP If you only need a single database handle, all the following return the same one: .PP .Vb 5 \& 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 .Ve .PP You can use the same requests again if you need to use the same test databases over several test scripts. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Test::Database provides a simple way for test authors to request a test database, without worrying about environment variables or the test host configuration. .PP See \s-1SYNOPSIS\s0 for typical usage. .PP See Test::Database::Tutorial for more detailed explanations. .SH "METHODS" .IX Header "METHODS" Test::Database provides the following methods: .SS "list_drivers" .IX Subsection "list_drivers" .Vb 2 \& my @drivers = Test::Database\->list_drivers(); \& my @drivers = Test::Database\->list_drivers(\*(Aqavailable\*(Aq); .Ve .PP Return a list of driver names of the given \*(L"type\*(R". .PP \&\f(CW\*(C`all\*(C'\fR returns the list of all existing Test::Database::Driver subclasses. .PP \&\f(CW\*(C`available\*(C'\fR returns the list of Test::Database::Driver subclasses for which the matching \&\f(CW\*(C`DBD\*(C'\fR class is available. .PP Called with no parameter (or anything not matching \f(CW\*(C`all\*(C'\fR or \f(CW\*(C`available\*(C'\fR), it will return the list of currently loaded drivers. .SS "drivers" .IX Subsection "drivers" Returns the Test::Database::Driver instances that are setup by \&\f(CW\*(C`load_drivers()\*(C'\fR and updated by \f(CW\*(C`load_config()\*(C'\fR. .SS "load_drivers" .IX Subsection "load_drivers" Load the available drivers from the system (file-based drivers, usually). .SS "load_config" .IX Subsection "load_config" .Vb 1 \& Test::Database\->load_config($config); .Ve .PP Read configuration from the files in \f(CW@files\fR. .PP If no file is provided, the local equivalent of \fI~/.test\-database\fR is used. .SS "clean_config" .IX Subsection "clean_config" .Vb 1 \& Test::Database\->clean_config(); .Ve .PP Empties whatever configuration has already been loaded. Also removes the loaded drivers list. .SS "handles" .IX Subsection "handles" .Vb 1 \& my @handles = Test::Database\->handles(@requests); .Ve .PP Return a set of Test::Database::Handle objects that match the given \f(CW@requests\fR. .PP If \f(CW@requests\fR is not provided, return all the available handles. .PP See \s-1REQUESTS\s0 for details about writing requests. .SS "handle" .IX Subsection "handle" .Vb 1 \& my $handle = Test::Database\->handle(@requests); .Ve .PP \&\fISingular\fR version of \f(CW\*(C`handles()\*(C'\fR, that returns the first matching handle. .SH "REQUESTS" .IX Header "REQUESTS" The \f(CW\*(C`handles()\*(C'\fR method takes \fIrequests\fR as parameters. A request is a simple hash reference, with a number of recognized keys. .IP "\(bu" 4 \&\f(CW\*(C`dbd\*(C'\fR: driver name (based on the \f(CW\*(C`DBD::\*(C'\fR name). .Sp \&\f(CW\*(C`driver\*(C'\fR is an alias for \f(CW\*(C`dbd\*(C'\fR. If the two keys are present, the \f(CW\*(C`driver\*(C'\fR key will be ignored. .Sp If missing, all available drivers will match. .IP "\(bu" 4 \&\f(CW\*(C`version\*(C'\fR: exact database engine version .Sp Only database engines having a version string identical to the given version string will match. .IP "\(bu" 4 \&\f(CW\*(C`min_version\*(C'\fR: minimum database engine version .Sp Only database engines having a version number greater or equal to the given minimum version will match. .IP "\(bu" 4 \&\f(CW\*(C`max_version\*(C'\fR: maximum database engine version .Sp Only database engines having a version number lower (and not equal) to the given maximum version will match. .IP "\(bu" 4 \&\f(CW\*(C`regex_version\*(C'\fR: matching database engine version .Sp Only database engines having a version string that matches the given regular expression will match. .PP A request can also consist of a single string, in which case it is interpreted as a shortcut for \f(CW\*(C`{ dbd =\*(C'\fR \f(CW$string\fR }>. .SH "FILES" .IX Header "FILES" The list of available, authorized \s-1DSN\s0 is stored in the local equivalent of \fI~/.test\-database\fR. It's a simple list of key/value pairs, with the \&\f(CW\*(C`dsn\*(C'\fR, \f(CW\*(C`driver_dsn\*(C'\fR or \f(CW\*(C`key\*(C'\fR keys being used to split successive entries: .PP .Vb 4 \& # 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 .Ve .PP The \f(CW\*(C`username\*(C'\fR and \f(CW\*(C`password\*(C'\fR keys are optional and \f(CW\*(C`undef\*(C'\fR will be used if they are not provided. .PP Empty lines and comments are ignored. .PP Optionally, the \f(CW\*(C`key\*(C'\fR section is used to add a \*(L"unique\*(R" element to the databases created by the drivers (as defined by \f(CW\*(C`driver_dsn\*(C'\fR). 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. .PP Individual drivers may accept extra parameters. See their documentation for details. Unrecognized parameters and not used, and therefore ignored. .SH "AUTHOR" .IX Header "AUTHOR" Philippe Bruhat (BooK), \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-test\-database at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Test::Database .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "TODO" .IX Header "TODO" Some of the items on the \s-1TODO\s0 list: .IP "\(bu" 4 Add a database engine autodetection script/module, to automatically write the \fI.test\-database\fR configuration file. .SH "HISTORY" .IX Header "HISTORY" Quoting Michael Schwern: .PP \&\fIThere's plenty of modules which need a database, and they all have to be configured differently and they're always a \s-1PITA\s0 when you first install and each and every time they upgrade.\fR .PP \&\fIUser 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.\fR .PP See for the thread that led to the creation of Test::Database. .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to \f(CW\*(C`\*(C'\fR for early comments. .PP 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. .PP Thanks to Mark Lawrence for discussing this module with me, and sending me an alternative implementation to show me what he needed. .PP 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. .PP The work leading to the new implementation (version 0.99 and later) was carried on during the Perl \s-1QA\s0 Hackathon, held in Birmingham in March 2009. Thanks to Birmingham.pm for organizing it and to Booking.com for sending me there. .PP Thanks to the early adopters: Alexis Sukrieh (\s-1SUKRIA\s0), Nicholas Bamber (\s-1SILASMONK\s0) and Adam Kennedy (\s-1ADAMK\s0). .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2008\-2010 Philippe Bruhat (BooK), all rights reserved. .SH "LICENSE" .IX Header "LICENSE" This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.