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.

