/ 
SimpleMock-0.02
/ DBD::SimpleMock

NAME

DBD::SimpleMock - A mock DBD for testing DBI applications

SYNOPSIS

Generally, you will use this directly via the SimpleMock module, but see the test for a standalone usage example.

use SimpleMock qw(register_mocks);
use Module::To::Test;
my $d1 = [
    [ 'Clive', 'clive@testme.com' ],
    [ 'Colin', 'colin@testme.com' ],
];

my $d2 = [
    [ 'Dave', 'dave@testme.com' ],
    [ 'Diane', 'diane@testme.com' ],
];

register_mocks(
    DBI => {
        # see below for global flags that can be set - by default they are all 0
        META => {
            allow_unmocked_queries => 0, # Set to 1 to allow unmocked queries to not be fatal
            connect_fail => 0,           # Set to 1 to simulate a connection failure
            prepare_fail => 0,           # Set to 1 to simulate a prepare failure
            execute_fail => 0,           # Set to 1 to simulate an execute failure
        },
        QUERIES => [
            {
                sql => 'SELECT id, name, email FROM my_table WHERE name LIKE ?',
                # each query can have multiple results defined based on placeholder values
                # note: the C%/D% in the args are literals on the actual args sent
                #       the code may be using a wild card, but the mocks are not aware of that
                results => [
                    { args => [ 'C%' ], data => $d1 },
                    { args => [ 'D%' ], data => $d2 },
                ],
                # define cols if using any of the *_hashref methods
                cols => [ 'id', 'name', 'email' ],
            },
        ],
    }
);

# call the code that runs the query
my $result = Module::To::Test->get_data('C%');
is_deeply $result, $d1, 'Got expected data for C%';

my $result2 = Module::To::Test->get_data('D%');
is_deeply $result2, $d2, 'Got expected data for D%';

done_testing();

DESCRIPTION

DBD::SimpleMock is a mock database driver for DBI that allows you to simulate database interactions in your tests without needing a real database connection. It is particularly useful for unit testing DBI-based applications.

USAGE

In your test, register your mock queries and their expected results using the `register_mocks` function from the SimpleMock module:

use Test::More;
use SimpleMock qw(register_mocks);
register_mocks(
    DBI => {
        # optional meta settings
        META => {
            ...
        },
        # each query must have an 'sql' and at least one 'results' entry
        # If you are using the `*_hashref` methods, you must also define 'cols'
        QUERIES => [
            {
                sql => 'SELECT id, name, email FROM my_table WHERE name LIKE ?',
                results => [
                    # data is an array ref of arrayrefs, each representing a row 
                    { args => [ 'C%' ], data => $d1 },
                    { args => [ 'D%' ], data => $d2 },
                    # no args means it will match any query with no placeholders
                    { data => $d3 }, # this will match any query without placeholders
                ],
                # optional, if you are using the *_hashref methods
                cols => [ 'id', 'name', 'email' ],
            },
        ],
    }
});

Meta tags are used to make aspects of the DBD to explicitly fail, or to allow unmocked queries to return empty results instead of throwing an exception.

META SETTINGS

These are the available flags you can set in the `META` section of your mocks registration:

  • `allow_unmocked_queries`: If set to 1, unmocked queries will return an empty result set and not throw an exception.

  • `connect_fail`: If set to 1, simulates a connection failure when connecting to the mock database.

  • `prepare_fail`: If set to 1, simulates a failure when preparing a statement.

  • `execute_fail`: If set to 1, simulates a failure when executing a statement.

Note that if you set connect_fail, prepare_fail & execute_fail are moot at that point, so best practice is to only enable each as needed by the test.