The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Class::DBI::Test::TempDB - Maintain a SQLite database for testing CDBI

Version

Version 1.0

Synopsis

     package Music::TempDB;
     use base qw/Class::DBI::Test::TempDB/;

     __PACKAGE__->build_test_db();

     END {
         __PACKAGE__->tear_down_connection(); 
        # remove the db file at unload time
     }

     1;

     # ...Meanwhile, somewhere in Music::CD:

     =begin testing

     use Music::TempDB;
     # have our class use the test db:
     Music::TempDB->connect_class_to_test_db('Music::CD');

     # create some data in our test db:
     my $cd = Music::CD->create({
        title => "Jimmy Thudpucker's Greatest Hits",
        year  => 1978
     });

     # make sure it looks right:
     is($cd->year, 1978, 'year');
     # etc.

     # ... when done testing, delete data:
     $cd->delete();

     =end testing

Description

In testing, we generally want tests to create and destroy all their own data. When writing Class::DBI-based projects, it's helpful to have a test database in which to do this, so that we can (a) be sure we're not stepping on production data, and (b) be sure of exactly what data is in the test database at the beginning/end of each test.

Class::DBI::Test::TempDB handles the creation and destruction of a temporary SQLite database on disk; it also allows you to point your Class::DBI classes at the test database. You can then get on with creating, testing and destroying test data simply by interacting with your Class::DBI classes.

The database can be persistent between tests, or it can be recreated for each test, from a YAML file describing the schema to be created. It can be stored in a temp file, or in a file with a user-supplied name.

Everything is done through class methods and subclassing.

Methods

build_connection

If supplied a parameter, that parameter is used as the name of a database file to be built (or connected to, if it already exists). If not, creates a temporary file (using File::Temp). Once the file is created, this method initializes a SQLite db in it, and points our package connection at it.

dsn

Returns the string 'dbi:SQLite:dbname=' . <the name of the database file being used>

tear_down_connection

Removes the database file, if it still exists.

connect_class_to_test_db

Overrides the db_Main() method of the passed-in CDBI entity class so that it calls our db_Main() instead. This is the methodology suggested by the CDBI documentation for dynamically changing a class's database connection. NB the warnings there about already-existing instances of the entity class: that is, this should probably only be done at the beginning of a test script, before any objects have been instantiated in the entity class.

build_test_db

 MyClass::DBI::Test->build_test_db(<$yaml, $dbfile>);

Given the path to a YAML file representing the schema of our production database, generate a test SQLite database and use it.

By default, $yaml is 'config.yaml' and $dbfile is a temp file (we use File::Temp, which see for details).

The YAML file is expected to be in the format produced by SQL::Translator (which see for details); here's an example of a way to produce such a YAML file from a MySQL database called 'mydatabase':

  mysqldump -d mydatabase | perl -MSQL::Translator -e 
    'my $sql = join "", <STDIN>; my $trans = SQL::Translator->new; 
    print $trans->translate(from => "MySQL", to => "YAML", data => $sql);' 
    > config.yaml

See Also

Class::DBI, SQL::Translator, File::Temp

Limitations

Of course, this module can only handle things that SQLite can handle.

Author

Dan Friedman, <lamech@cpan.org>

Acknowledgements

Thanks to Kirrily "Skud" Robert for early design input.

Thanks to Tony Bowden for module naming help.

Lots of ideas were taken from the testsuite that accompanies Class::DBI.

Bugs

Please report any bugs or feature requests to bug-class-dbi-test-tempdb@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Copyright & License

Copyright 2004 Dan Friedman, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.