NAME

SimpleMock::Model::DBI - A mock model for DBI queries

DESCRIPTION

This module provides a mock model for DBI queries, allowing you to register mock queries and their results. It normalizes queries and handles argument-based mocking.

Metadata can be set to control behavior such as allowing unmocked queries, or to force failure on certain operations like `prepare`, `execute` or `connect`.

USAGE

You probably won't want to use this module directly, but rather use the SimpleMock module in your tests instead:

use SimpleMock qw(register_mocks);

register_mocks(
    DBI => {
        # all meta values default to false if not explicitly set
        META => {
            # 0|1 allow queries that are not mocked to run with a default empty result set
            'allow_unmocked_queries' => 1,

            # 0|1 if true, then $dbh->connect returns undef (use for error checking tests)
            'connect_fail' => 0,

            # 0|1 if true, then $dbh->prepare fails with invalid SQL error
            'prepare_fail' => 0,
        
            # 0|1 if true, then $sth->execute returns undef (use for error checking tests)
            'execute_fail' => 0,
        },
        # QUERIES is an array of individual sql statements and what to return when executed
        # with specific args
        QUERIES => [
            {
                sql => 'SELECT name, email FROM users WHERE id = ?',
                results => [

                    # specific result data for arg sent
                    { args => [1],
                      data => [ ['Alice', 'alice@example.com'] ] },

                    # specific result data for arg sent
                    { args => [2],
                      data => [ ['Bob', 'bob@example.com'] ] },

                    # result data for all other args
                    { data => [ ['Default', 'default@example.com'] ] },

                ],
            },
        ],
    },
);

For each query, specify the SQL statement. Then, in the results array, provide the placeholder args and data to return for each, and an optional default result that only has a data element to use as a default for query executions where there is no args match