NAME
    Test::WithDB - Framework for testing application using database

VERSION
    This document describes version 0.03 of Test::WithDB (from Perl
    distribution Test-WithDB), released on 2014-09-18.

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=

    In your test file:

     use Test::More;
     use Test::WithDB;

     my $twdb = Test::WithDB->new;

     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.

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

METHODS
  new(%attrs) => obj
  $twdb->create_db
    Create a test database with random name.

  $twdb->done
    Finish testing. Will drop all created databases unless tests are not
    passing.

    Called automatically during DESTROY (but because object destruction
    order are not guaranteed, it's best that you explicitly call "done()"
    yourself).

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: .)
ENVIRONMENT
  TWDB_CONFIG_PATH => str
    Set default "config_path".

  TWDB_CONFIG_PROFILE => str
    Set default "config_profile".

SEE ALSO
    Test::More, Test::Builder

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.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 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.