NAME Test::WithDB - Framework for testing application using database VERSION This document describes version 0.100 of Test::WithDB (from Perl distribution Test-WithDB), released on 2018-05-10. SYNOPSIS In your "~/test-withdb.ini": admin_dsn ="dbi:Pg;host=localhost" admin_user="postgres" admin_pass="adminpass" user_dsn ="dbi:Pg;host=localhost" user_user="someuser" user_pass="somepass" # optional: SQL statements to initialize DB by test user after created init_sql_admin=CREATE EXTENSION citext # optional: SQL statements to initialize DB by test user after created init_sql_user= Or, if you want to put multiple configuration in your config file you can use config profiles: [profile=pg] admin_dsn ="dbi:Pg;host=localhost" admin_user="postgres" admin_pass="adminpass" user_dsn ="dbi:Pg;host=localhost" user_user="someuser" user_pass="somepass" [profile=mysql] admin_dsn ="dbi:mysql" admin_user="root" admin_pass="adminpass" user_dsn ="dbi:mysql" user_user="someuser" user_pass="somepass" ... In your test file: use Test::More; use Test::WithDB; my $twdb = Test::WithDB->new( #driver => '...', # optional. preferred DBI driver, e.g. Pg, or mysql. #config_path => '...', # optional. defaults to TWDB_CONFIG_PATH env or ~/test-withdb.ini or ~/twdb.ini #config_profile => '...', # optional. defaults to TWDB_CONFIG_PROFILE_ env (if driver is specified), or TWDB_CONFIG_PROFILE, or undef #name_pattern => '...', # optional. defaults to TWDB_NAME_PATTERN env or 'testdb_%u' ); my $dbh = $twdb->create_db; # create db with random name # do stuffs with dbh my $dbh2 = $twdb->create_db; # create another db # do more stuffs $twdb->done; # will drop all created databases, unless tests are not passing DESCRIPTION This class ("Test::WithDB", or TWDB for short) provides a simple framework for testing application that requires database. It is meant to work with Test::More (or to be more exact, any Test::Builder-based module). It offers an easy way to create random databases and initialize them so they are ready for testing. More functionalities will be added in the future. To work with TWDB, first, you supply a configuration file containing admin and normal user's connection information (the admin info is needed to create databases). Then, you call one or more "create_db()" to create one or more databases for testing. The database will be created with random names. At the end of testing, when you call "$twdb->done", the class will do this check: if (Test::More->builder->is_passing) { # drop all created databases } else { diag "Tests failing, not removing databases created during testing: ..."; } So when testing fails, you can inspect the database. Currently only supports Postgres, MySQL, and SQLite; and tested mostly with Postgres. CONFIGURATION *admin_dsn => str *admin_user => str *admin_pass => str *user_dsn => str *user_user => str *user_pass => str init_sql_admin => str|array init_sql_user => str|array sqlite_db_dir => str (default: .) ATTRIBUTES driver => str Preferred DBI driver. If set, this will make Test::WithDB consult TWDB_CONFIG_PROFILE_*DRIVER* environment variable before "TWDB_CONFIG_PROFILE" to set default value for config_profile. For example, if you set driver to "mysql", then "TWDB_CONFIG_PROFILE_MYSQL" will be consulted first before "TWDB_CONFIG_PROFILE". config_path => str (default: "~/test-withdb.ini" or "~/twdb.ini"). Path to configuration file. File will be read using Config::IOD::Reader. config_profile => str (default: GLOBAL) Pick section in configuration file to use. name_pattern => str (default: "testdb_%Y%m%d_%H%M%S_%u") Pattern for random database name, where several sprintf-/strftime-style %X directives are recognized: * "%%" Literal percentage sign * %U 32-character random UUID hex. It is recommended that at least you add either this or %u. * %u 8-character prefix of random UUID hex. It is recommended that at least you add either this or %u. If you use %u instead of %U, it is recommended that you also add timestamp. * %Y 4-digit year of current time. * %m 2-digit month (01-12) of current time. * %d 2-digit day of month (01-31) of current time. * %H 2-digit hour (00-23) of current time. * %M 2-digit minute (00-59) of current time. * %S 2-digit second (00-60) of current time. You should make sure that the database name won't exceed the maximum length allowed by the database software (e.g. 64 character for some SQL databases). METHODS new(%attrs) => obj $twdb->create_db Create a test database with random name according to "name_pattern". $twdb->created_dbs => LIST Return a list of temporary databases already created by this instance. $twdb->done Finish testing. Will drop all created databases unless tests are not passing or "TWDB_KEEP_TEMP_DBS" is set to true. Called automatically during DESTROY (but because object destruction order are not guaranteed, e.g. DBI database handle might get destroyed first preventing proper database deletion to work, it's best that you explicitly call "done()" yourself). $twdb->drop_dbs Explicitly delete created temporary databases, regardless of whether tests are passing or "TWDB_KEEP_TEMP_DBS" is set. ENVIRONMENT TWDB_CONFIG_PATH => str Set default "config_path". TWDB_CONFIG_PROFILE => str Set default "config_profile". TWDB_NAME_PATTERN => str Set default "name_pattern". TWDB_KEEP_TEMP_DBS => bool Can be set to true to keep "done()" from automatically dropping databases. HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. SEE ALSO DBIx::TempDB Test::More, Test::Builder AUTHOR perlancar COPYRIGHT AND LICENSE This software is copyright (c) 2018, 2017, 2016, 2015, 2014 by perlancar@cpan.org. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.