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 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 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

DBIx::TempDB

Test::More, Test::Builder

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.

cpanm Test::WithDB

perl -MCPAN -e shell
install Test::WithDB