diff options
Diffstat (limited to 'lib/Test/Database/Tutorial.pod')
| -rw-r--r-- | lib/Test/Database/Tutorial.pod | 66 |
1 files changed, 33 insertions, 33 deletions
diff --git a/lib/Test/Database/Tutorial.pod b/lib/Test/Database/Tutorial.pod index becb608..b402dd4 100644 --- a/lib/Test/Database/Tutorial.pod +++ b/lib/Test/Database/Tutorial.pod @@ -4,7 +4,7 @@ Test::Database::Tutorial - How to use Test::Database =head1 INTRODUCTION -The goal of the C<Test::Database> module is to provide easy to use test +The goal of the L<Test::Database> module is to provide easy to use test databases for test scripts that need them. =head2 The problem @@ -54,7 +54,7 @@ be at risk! =back -=head2 A solution: C<Test::Database> +=head2 A solution: L<Test::Database> Many modules use a database to store their data, and often support several database engines. @@ -62,7 +62,7 @@ several database engines. Wouldn't it be nice to be able to test on all the supported databases that are available on the test system? Without breaking (into) anything? -This is the goal of the C<Test::Database> module. It supports: +This is the goal of the L<Test::Database> module. It supports: =over 4 @@ -76,28 +76,28 @@ automatic detection of "file-based" database engines (typically, SQLite). =back -The rest of this document describes various use cases for C<Test::Database>. +The rest of this document describes various use cases for L<Test::Database>. =head1 MODULE AND TEST AUTHOR -C<Test::Database> has a single interface for test authors: +L<Test::Database> has a single interface for test authors: my @handles = Test::Database->handles( @requests ); C<@request> is a list of "requests" for databases handles. Requests must declare the DBD they expect, and can optionaly add version-based -limitations (only available for drivers supported by C<Test::Database>). +limitations (only available for drivers supported by L<Test::Database>). -The handles returned are objects of the C<Test::Database::Handle> class. +The handles returned are objects of the L<Test::Database::Handle> class. The data contained in the database is never destroyed or cleaned -up by C<Test::Database>, so it's perfectly fine to have a startup script +up by L<Test::Database>, so it's perfectly fine to have a startup script that will setup the necessary tables and test data, several tests scripts that will build and update the data, and a eventually a teardown script that will drop all created tables. -C<Test::Database> can return two types of databases handles: +L<Test::Database> can return two types of databases handles: =over 4 @@ -118,7 +118,7 @@ In any case, the database is assumed to provide C<DROP TABLE> and C<CREATE TABLE> rights, and the test script is by definition allowed to do whatever it pleases with the tables that exist in the database. -Note that C<Test::Database> supports any DSN, not just those for which +Note that L<Test::Database> supports any DSN, not just those for which it has a driver. If your module supports Oracle, you can add C<'Oracle'> to your list of requests, and if the host owner configured a C<dsn> pointing at an Oracle database, then it will be available for your tests. @@ -159,11 +159,11 @@ A typical F<~/.test-database> configuration file would look like this: dsn = dbi:Oracle:test There is no need to add C<dsn> sections for file-based drivers -(at least the ones that have a corresponding C<Test::Database::Driver>), +(at least the ones that have a corresponding L<Test::Database::Driver>), since the module will automatically detect the available ones and create databases as needed. -To find out which of the DBD that C<Test::Database> supports are +To find out which of the DBD that L<Test::Database> supports are installed, use the following one-liner: $ perl -MTest::Database -le 'print for Test::Database->list_drivers("available")' @@ -180,10 +180,10 @@ With no parameter, it will return the list of configured ones: =head1 CPAN TESTER -The main goal of C<Test::Database> from the point of view of a tester +The main goal of L<Test::Database> from the point of view of a tester is: "configure once, test everything". -As a CPAN tester, once you have installed C<Test::Database>, you +As a CPAN tester, once you have installed L<Test::Database>, you should edit the local equivalent of F<~/.test-database> for the user that will be running the CPAN test suites. @@ -195,12 +195,12 @@ requests it. C<driver_dsn> sections define the information needed to connect to a database engine (a "driver") with sufficient rights to run a -C<CREATE DATABASE> command. This allows C<Test::Database> to create the +C<CREATE DATABASE> command. This allows L<Test::Database> to create the databases on demand, thus ensuring every test suite will get a specific database. If you have file-based database engine, there is nothing to setup, as -C<Test::Database> is able to detect available file-based engines and +L<Test::Database> is able to detect available file-based engines and use them as needed. Other database engines like C<mysql> and C<Pg> require a little more @@ -222,27 +222,27 @@ If you have a large scale testing setup, you may want to setup a single MySQL or Postgres instance for all your test hosts, rather than one per test host. -Databases created by C<Test::Database::Driver> (using a configured +Databases created by L<Test::Database::Driver> (using a configured C<driver_dsn> have a name built after the following template: C<tdd_I<driver>_I<login>_I<n>>, where I<driver> is the DBD name, I<login> -is the login of the user running C<Test::Database> and I<n> a number that +is the login of the user running L<Test::Database> and I<n> a number that If the same database server is used by several host running -C<Test::Database> from the same user account, there is a race condition +L<Test::Database> from the same user account, there is a race condition during with two different host may try to create the a database with the same name. A simple trick to avoid this is to add a C<key> section to the F<~/.test-database> configuration file. -If the C<key> entry exists, the template used by C<Test::Database::Driver> +If the C<key> entry exists, the template used by L<Test::Database::Driver> to create new databases is C<tdd_I<driver>_I<login>_I<key>_I<n>>. =head2 Cleaning the test drivers -When given a C<driver_dsn>, C<Test::Database> will use it to create a +When given a C<driver_dsn>, L<Test::Database> will use it to create a database for each test suite that requests one. Some mapping information is created to ensure the same test suite always receives a handle to the same database. (The mapping of test suite to database is based on -the current working directory when C<Test::Database> is loaded). +the current working directory when L<Test::Database> is loaded). After a while, your database engine may fill up with unused test databases. @@ -253,7 +253,7 @@ file-based drivers store their database files in the system's temporary directory too). The following one-liner will list all the existing databases that were -created by C<Test::Database> in your configured drivers: +created by L<Test::Database> in your configured drivers: perl -MTest::Database -le 'print join "\n ", $_->name, $_->databases for Test::Database->drivers' @@ -281,22 +281,22 @@ corresponding to that key will be dropped. =head1 ADDING SUPPORT FOR A NEW DATABASE ENGINE -C<Test::Database> currently supports the following DBD drivers: +L<Test::Database> currently supports the following DBD drivers: C<CSV>, C<DBM>, C<mysql>, C<Pg>, C<SQLite2>, C<SQLite>. Adding a new driver requires writing a corresponding -C<Test::Database::Driver> subclass, having the same name as the original +L<Test::Database::Driver> subclass, having the same name as the original C<DBD> driver. An example module is provided in F<eg/MyDriver.pm>, and the other drivers can also be used as an example. See also the I<WRITING A DRIVER FOR YOUR DATABASE OF CHOICE> section in the documentation for -C<Test::Database::Driver>. +L<Test::Database::Driver>. =head1 WHERE DO DSN COME FROM? -The following ASCII-art graph shows where the C<Test::Database::Handle> +The following ASCII-art graph shows where the L<Test::Database::Handle> objects returned by the C<handles()> method come from: @@ -322,32 +322,32 @@ Here are a few details about the C<handles()> method works: =item * -C<Test::Database> maintains a list of C<Test::Database::Handle> objects +L<Test::Database> maintains a list of L<Test::Database::Handle> objects computed from the DSN listed in the configuration. The handles matching the request are selected. =item * -C<Test::Database> also maintains a list of C<Test::Database::Driver> +L<Test::Database> also maintains a list of L<Test::Database::Driver> objects computed from the list of supported file-based drivers that are locally available and from the list in the configuration file. The list of matching drivers is computed from the requests. Each driver is then requested to provide an existing database (using its existing mapping information) or to create one if needed, and returns the -corresponding C<Test::Database::Handle> objects. +corresponding L<Test::Database::Handle> objects. =item * -Finally, all the collected C<Test::Database::Handle> objects are returned. +Finally, all the collected L<Test::Database::Handle> objects are returned. =back -So, without any configuration, C<Test::Database> will only be able to +So, without any configuration, L<Test::Database> will only be able to provide file-based databases. It is also recommended to B<not> put DSN or driver information for the file-based database engines that have -a corresponding C<Test::Database::Driver> class, since it will cause +a corresponding L<Test::Database::Driver> class, since it will cause C<handles()> to return several handles for the same database engine. =head1 AUTHOR |