1Test::Database(3) User Contributed Perl Documentation Test::Database(3)
2
6 Test::Database - Database handles ready for testing
7
9 Maybe you wrote generic code you want to test on all available
10 databases:
11 use Test::More;
13 use Test::Database;
14 # get all available handles
16 my @handles = Test::Database->handles();
17 # plan the tests
19 plan tests => 3 + 4 * @handles;
20 # run the tests
22 for my $handle (@handles) {
23 diag "Testing with " . $handle->dbd(); # mysql, SQLite, etc.
24 # there are several ways to access the dbh:
26 # let $handle do the connect()
28 my $dbh = $handle->dbh();
29 # do the connect() yourself
31 my $dbh = DBI->connect( $handle->connection_info() );
32 my $dbh = DBI->connect( $handle->dsn(), $handle->username(),
33 $handle->password() );
34 }
35 It's possible to limit the results, based on the databases your code
37 supports:
38 my @handles = Test::Database->handles(
40 'SQLite', # SQLite database
41 { dbd => 'mysql' }, # or mysql database
42 { driver => 'Pg' }, # or Postgres database
43 );
44 # use them as above
46 If you only need a single database handle, all the following return the
48 same one:
49 my $handle = ( Test::Database->handles(@requests) )[0];
51 my ($handle) = Test::Database->handles(@requests);
52 my $handle = Test::Database->handles(@requests); # scalar context
53 my $handle = Test::Database->handle(@requests); # singular!
54 my @handles = Test::Database->handle(@requests); # one or zero item
55 You can use the same requests again if you need to use the same test
57 databases over several test scripts.
58
60 Quoting Michael Schwern:
61 There's plenty of modules which need a database, and they all have to
63 be configured differently and they're always a PITA when you first
64 install and each and every time they upgrade.
65 User setup can be dealt with by making Test::Database a build
67 dependency. As part of Test::Database's install process it walks the
68 user through the configuration process. Once it's done, it writes out a
69 config file and then it's done for good.
70 See <http://www.nntp.perl.org/group/perl.qa/2008/10/msg11645.html> for
72 the thread that led to the creation of "Test::Database".
73 "Test::Database" provides a simple way for test authors to request a
75 test database, without worrying about environment variables or the test
76 host configuration.
77 See SYNOPSIS for typical usage.
79
81 "Test::Database" provides the following methods:
82 list_drivers( [$type] )
84 Return a list of driver names of the given "type".
85 "all" returns the list of all existing "Test::Database::Driver"
87 subclasses.
88 "available" returns the list of "Test::Database::Driver" subclasses
90 for which the matching "DBD" class is available.
91 Called with no parameter (or anything not matching "all" or
93 "available"), it will return the list of currently loaded drivers.
94 drivers()
96 Returns the "Test::Database::Driver" instances that are setup by
97 "load_drivers()" and updated by "load_config()".
98 load_drivers()
100 Load the available drivers from the system (file-based drivers,
101 usually).
102 load_config( @files )
104 Read configuration from the files in @files.
105 If no file is provided, the local equivalent of ~/.test-database is
107 used.
108 clean_config()
110 Empties whatever configuration has already been loaded. Also
111 removes the loaded drivers list.
112 handles( @requests )
114 Return a set of "Test::Database::Handle" objects that match the
115 given @requests.
116 If @requests is not provided, return all the available handles.
118 See REQUESTS for details about writing requests.
120 handle( @request )
122 Singular version of "handles()", that returns the first matching
123 handle.
124
126 The "handles()" method takes requests as parameters. A request is a
127 simple hash reference, with a number of recognized keys.
128 · "dbd": driver name (based on the "DBD::" name).
130 "driver" is an alias for "dbd". If the two keys are present, the
132 "driver" key will be ignored.
133 If missing, all available drivers will match.
135 · "version": exact database engine version
137 Only database engines having a version string identical to the
139 given version string will match.
140 · "min_version": minimum database engine version
142 Only database engines having a version number greater or equal to
144 the given minimum version will match.
145 · "max_version": maximum database engine version
147 Only database engines having a version number lower (and not equal)
149 to the given maximum version will match.
150 · "regex_version": matching database engine version
152 Only database engines having a version string that matches the
154 given regular expression will match.
155 A request can also consist of a single string, in which case it is
157 interpreted as a shortcut for "{ dbd =" $string }>.
158
160 The list of available, authorized DSN is stored in the local equivalent
161 of ~/.test-database. It's a simple list of key/value pairs, with the
162 "dsn", "driver_dsn" or "key" keys being used to split successive
163 entries:
164 # mysql
166 dsn = dbi:mysql:database=mydb;host=localhost;port=1234
167 username = user
168 password = s3k r3t
169 # Oracle
171 dsn = dbi:Oracle:test
172 # set a unique key when creating databases
174 key = thwapp
175 # a "driver" with full access (create/drop databases)
177 driver_dsn = dbi:mysql:
178 username = root
179 The "username" and "password" keys are optional and empty strings will
181 be used if they are not provided.
182 Empty lines and comments are ignored.
184 Optionaly, the "key" section is used to add a "unique" element to the
186 databases created by the drivers (as defined by "driver_dsn"). It
187 allows several hosts to share access to the same database server
188 without risking a race condition when creating a new database. See
189 Test::Database::Tutorial for a longer explanation.
190 Individual drivers may accept extra parameters. See their documetation
192 for details. Unrecognized parameters and not used, and therefore
193 ignored.
194
196 Philippe Bruhat (BooK), "<book@cpan.org>"
197
199 Please report any bugs or feature requests to "bug-test-database at
200 rt.cpan.org", or through the web interface at
201 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Database
202 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Database>. I will
203 be notified, and then you'll automatically be notified of progress on
204 your bug as I make changes.
205
207 You can find documentation for this module with the perldoc command.
208 perldoc Test::Database
210 You can also look for information at:
212 · RT: CPAN's request tracker
214 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Database
216 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Database>
217 · AnnoCPAN: Annotated CPAN documentation
219 http://annocpan.org/dist/Test-Database
221 <http://annocpan.org/dist/Test-Database>
222 · CPAN Ratings
224 http://cpanratings.perl.org/d/Test-Database
226 <http://cpanratings.perl.org/d/Test-Database>
227 · Search CPAN
229 http://search.cpan.org/dist/Test-Database
231 <http://search.cpan.org/dist/Test-Database>
232
234 Some of the items on the TODO list:
235 · Add a database engine autodetection script/module, to automatically
237 write the .test-database configuration file.
238
240 Thanks to "<perl-qa@perl.org>" for early comments.
241 Thanks to Nelson Ferraz for writing "DBIx::Slice", the testing of which
243 made me want to have a generic way to obtain a test database.
244 Thanks to Mark Lawrence for discussing this module with me, and sending
246 me an alternative implementation to show me what he needed.
247 Thanks to Kristian Koehntopp for helping me write a mysql driver, and
249 to Greg Sabino Mullane for writing a full Postgres driver, none of
250 which made it into the final release because of the complete change in
251 goals and implementation between versions 0.02 and 0.03.
252 The work leading to the new implementation (version 0.99 and later) was
254 carried on during the Perl QA Hackathon, held in Birmingham in March
255 2009. Thanks to Birmingham.pm for organizing it and to Booking.com for
256 sending me there.
257 Thanks to the early adopters: Alexis Sukrieh (SUKRIA), Nicholas Bamber
259 (SILASMONK) and Adam Kennedy (ADAMK).
260
262 Copyright 2008-2010 Philippe Bruhat (BooK), all rights reserved.
263
265 This module is free software; you can redistribute it and/or modify it
266 under the same terms as Perl itself.
267perl v5.12.3 2011-03-15 Test::Database(3)