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_<DRIVER> 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 passingDESCRIPTION
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
%U32-character random UUID hex. It is recommended that at least you add either this or
%u.%u8-character prefix of random UUID hex. It is recommended that at least you add either this or
%u. If you use%uinstead of%U, it is recommended that you also add timestamp.%Y4-digit year of current time.
%m2-digit month (01-12) of current time.
%d2-digit day of month (01-31) of current time.
%H2-digit hour (00-23) of current time.
%M2-digit minute (00-59) of current time.
%S2-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 https://metacpan.org/release/Test-WithDB.
SOURCE
Source repository is at https://github.com/perlancar/perl-Test-WithDB.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Test-WithDB
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
AUTHOR
perlancar <perlancar@cpan.org>
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.