---
name: "DBI::Test"
section: "3pm"
platform: "linux"
package: "libdbi-test-perl"
version: "0.001-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/DBI::Test"
---

# DBI::Test(3pm)

Test suite for DBI API

## NAME

DBI::Test - Test suite for DBI API

## SYNOPSIS

In Makefile.PL:

```
    use lib 'lib'; # to allow DBI::Test finds the test cases of your driver
    use DBI::Test::Conf ();
    my @generated_tests = DBI::Test::Conf->setup();
    WriteMakefile (
        test => {
            TESTS           => join (' ' => 'xt/*.t', @generated_tests),
        },
        clean => { FILES => join( " " => @generated_tests ) }
    );
```

You provide

```
    package DBI::Test::Your::Namespace::List;

    sub test_cases
    {
        return qw(...); # list of the test cases you provide
    }

    package DBI::Test::Your::Namespace::Conf;

    sub conf
    {
        my %conf = (
            gofer => {
                         category   => "Gofer",
                         cat_abbrev => "g",
                         abbrev     => "b",
                         init_stub  => qq(\$ENV{DBI_AUTOPROXY} = 'dbi:Gofer:transport=null;policy=pedantic';),
                         match      => sub {
                                         my ($self, $test_case, $namespace, $category, $variant) = @_;
                                         ...
                                  },
                         name => "Gofer Transport",
                       },
                   );
    }

    package DBI::Test::Your::Namespace::Case::Your::First;

    ... # will be t/your/namespace/your/first.t

    package DBI::Test::Your::Namespace::Case::Your::Second;

    ... # will be t/your/namespace/your/second.t

    1;
```

And enhance DBI::Test with own test cases.

## DESCRIPTION

This module aims to be a test suite for the DBI API and an underlying DBD driver, to check if the provided functionality is working and complete.

Part of this module is the ability for self-testing using *DBI::Mock*. This is not designed to be another *DBI::PurePerl* - it's designed to allow tests can be verified to work as expected in a sandbox. This is, of course, limited to DBI API itself and cannot load any driver nor really execute any action.

## EXPORTS

### connect\_ok

```
  $dbh = connect_ok($dsn, $user, $pass, \%attrs, $test_name);
```

connect\_ok invokes DBI-\> and proves the result in an *ok*. The created database handle (`$dbh`) is returned, if any.

### connect\_not\_ok

```
  $dbh = connect_not_ok($dsn, $user, $pass, \%attrs, $test_name);
```

connect\_not\_ok invokes DBI-\> and proves the result in an *ok* (but expects that there is no `$dsn` returned).  The created database handle (`$dbh`) is returned, if any.

### prepare\_ok

```
  $sth = prepare_ok($dbh, $stmt, \%attrs, $test_name);
```

prepare\_ok invokes `$dbh`-\>prepare and proves the result in an *ok*. The resulting statement handle (`$sth`) is returned, if any.

### execute\_ok

```
  $rv = execute_ok($sth, $test_name);
  $rv = execute_ok($sth, @bind_values, $test_name);
```

execute\_ok invokes `$sth`-\>excute and proves the result via *ok*. The value got from `$sth`-\>execute is returned.

### execute\_not\_ok

```
  $rv = execute_not_ok($sth, $test_name);
  $rv = execute_not_ok($sth, @bind_values, $test_name);
```

execute\_not\_ok invokes `$sth`-\>excute and proves the result via *is(undef)*. The value got from `$sth`-\>execute is returned.

### do\_ok

```
  $rv = do_ok($dbh, $test_name);
  $rv = do_ok($dbh, @bind_values, $test_name);
```

do\_ok invokes `$dbh`-\>do and proves the result via *ok*. The value got from `$dbh`-\>do / `$sth`-\>execute is returned.

### do\_not\_ok

```
  $rv = do_not_ok($dbh, $test_name);
  $rv = do_not_ok($dbh, @bind_values, $test_name);
```

do\_not\_ok invokes `$dbh`-\>do and proves the result via *is(undef)*. The value got from `$dbh`-\>do / `$sth`-\>execute is returned.

## GOAL

### TODO

### Source

Recent changes can be (re)viewed in the public GIT repository at GitHub \<https://github.com/perl5-dbi/DBI-Test\> Feel free to clone your own copy:

```
 $ git clone https://github.com/perl5-dbi/DBI-Test.git DBI-Test
```

### Contact

We are discussing issues on the DBI development mailing list 1) and on IRC 2)

```
 1) The DBI team <dbi-dev@perl.org>
 2) irc.perl.org/6667 #dbi
```

## SUPPORT

You can find documentation for this module with the perldoc command.

```
    perldoc SQL::Statement
```

You can also look for information at:

- •

  RT: CPAN's request tracker

  \<http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBI-Test\>

- •

  AnnoCPAN: Annotated CPAN documentation

  \<http://annocpan.org/dist/DBI-Test\>

- •

  CPAN Ratings

  \<http://cpanratings.perl.org/s/DBI-Test\>

- •

  CPAN Search

  \<http://search.cpan.org/dist/DBI-Test/\>

### Reporting bugs

If you think you've found a bug then please read "How to Report Bugs Effectively" by Simon Tatham: \<http://www.chiark.greenend.org.uk/~sgtatham/bugs.html\>.

Your problem is most likely related to the specific DBD driver module you're using. If that's the case then click on the 'Bugs' link on the \<http://metacpan.org\> page for your driver. Only submit a bug report against the DBI::Test itself if you're sure that your issue isn't related to the driver you're using.

## TEST SUITE

DBI::Test comes with some basic tests to test itself and DBI::Mock. The same tests are used for basic DBI self-tests as well as testing the SQL::Statement mock driver.

## EXAMPLES

??? Synopsis ???

## DIAGNOSTICS

???

## SEE ALSO

```
 DBI        - Database independent interface for Perl
 DBI::DBD   - Perl DBI Database Driver Writer's Guide
 Test::More - yet another framework for writing test scripts
```

## AUTHOR

This module is a team-effort. The current team members are

```
  H.Merijn Brand   (Tux)
  Jens Rehsack     (Sno)
  Peter Rabbitson  (ribasushi)
  Joakim TE<0x00f8>rmoen   (trmjoa)
```

## COPYRIGHT AND LICENSE

Copyright (C)2013 - The DBI development team

You may distribute this module under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.