NAME

DBUnit - Database test API

SYNOPSIS

    use DBUnit ':all';

    my $dbunit = DBUnit->new(connection_name => 'test');
    $dbunit->reset_schema($script);
    $dbunit->populate_schema($script);

    $dbunit->dataset(
        emp   => [empno => 1, ename => 'scott', deptno => 10],
        emp   => [empno => 2, ename => 'john', deptno => 10],
        bonus => [ename => 'scott', job => 'consultant', sal => 30],
    );
    #business logic here

    my $differences = $dbunit->expected_dataset(
        emp   => [empno => 1, ename => 'scott', deptno => 10],
        emp   => [empno => 2, ename => 'John'],
        emp   => [empno => 2, ename => 'Peter'],
    );

    $dbunit->reset_sequence('emp_seq');

    $dbunit->xml_dataset('t/file.xml');

    $dbunit->expected_xml_dataset('t/file.xml');

LOBs support (Large Object)

This code snippet will populate database blob_content column with the binary data pointed by file attribute, size of the lob will be stored in size_column

    $dbunit->dataset(
        emp   => [empno => 1, ename => 'scott', deptno => 10],
        image  => [id => 1, name => 'Moon'
            blob_content => {file => 'data/image1.jpg', size_column => 'doc_size'}
        ]
    );

This code snippet will validate database binary data with expected content pointed by file attribute,

    $dbunit->expected_dataset(
        emp   => [empno => 1, ename => 'scott', deptno => 10],
        image => [id => 1, name => 'Moon'
            blob_content => {file => 'data/image1.jpg', size_column => 'doc_size'}
        ]
    );
    or xml
    <dataset>
        <emp .../>
        <image id=>"1" name="Moon">
            <blob_content  file="t/bin/data1.bin" size_column="doc_size" />
        </image>
    </dataset>

DESCRIPTION

Database test framework to verify that your database data match expected set of values. It has ability to populate dataset and expected set from xml files.

EXPORT

None by default. reset_schema populate_schema expected_dataset expected_xml_dataset dataset xml_dataset by tag 'all'

ATTRIBUTES

connection_name

load_strategy

INSERT_LOAD_STRATEGY(default) Deletes all data from tables that are present in test dataset in reverse order unless empty table without attribute is stated, that force deletion in occurrence order In this strategy expected dataset is also tested against number of rows for all used tables.

REFRESH_LOAD_STRATEGY Merges (update/insert) data to the given dataset snapshot. In this scenario only rows in expected dataset are tested.

primary_key_definition_cache

This option is stored as hash_ref: the key is the table name with the schema prefix and value is stored as array ref of primary key column names.

METHODS

reset_schema

Resets schema

populate_schema

Populates database schema.

dataset

Synchronizes/populates database to the passed in dataset.

    $dbunit->dataset(
        table1 => [], #this deletes all data from table1 (DELETE FROM table1)
        table2 => [], #this deletes all data from table2 (DELETE FROM table2)
        table1 => [col1 => 'va1', col2 => 'val2'], #this insert or update depend on strategy
        table1 => [col1 => 'xval1', col2 => 'xval2'],
    )

expected_dataset

Validates database schema against passed in dataset. Return differences report or undef is there are not discrepancies.

    my $differences = $dbunit->expected_dataset(
        table1 => [col1 => 'va1', col2 => 'val2'],
        table1 => [col1 => 'xval1', col2 => 'xval2'],
    );

reset_sequence

Resets passed in sequence

xml_dataset

Loads xml file to dataset and populate/synchronize it to the database schema. Takes xml file as parameter.

    <dataset load_strategy="INSERT_LOAD_STRATEGY" reset_sequences="emp_seq">
        <emp ename="scott" deptno="10" job="project manager" />
        <emp ename="john"  deptno="10" job="engineer" />
        <emp ename="mark"  deptno="10" job="sales assistant" />
        <bonus ename="scott" job="project manager" sal="20" />
    </dataset>

expected_xml_dataset

Takes xml file as parameter. Return differences report or undef is there are not discrepancies.

apply_properties

Sets properties for this object.

PRIVATE METHODS

rows_to_insert

drop_objects

Removes existing schema

create_tables

objects_to_create

Returns list of pairs values('object_type object_name', create_sql, ..., 'object_typeN object_nameN', create_sqlN)

insert

Inserts data

merge

Merges passed in data

update

Updates table values.

has_primary_key_values

Returns true if passed in dataset have primary key values

primary_key_values

Returns primary key values, Takes table name, hash ref as fields of values, db connection object.

delete_data

Deletes data from passed in tables.

tables_to_delete

Returns list of tables to delete.

empty_tables_to_delete

Returns list of table that are part of dataset table and are represented by table without attributes

  table1 => [],

  or in xml file

  <table1 />

expected_dataset_for_insert_load_strategy

Validates expected dataset for the insert load strategy.

_update_lobs

Updates lobs.

_exp_table_with_column

Return hash ref of the tables with it columns.

_extract_column_values

_extract_column_values

_process_lob

validate_number_of_rows

Validates number of rows.

validate_dataset

Validates passed exp dataset against fetched rows. Return undef if there are not difference otherwise returns validation error.

validate_lobs

Validates lob values

expected_dataset_for_refresh_load_strategy

Validates expected dataset for the refresh load strategy.

validate_expexted_dataset

Validates passed exp dataset against database schema Return undef if there is not difference otherwise returns validation error.

compare_datasets

Compares two dataset hashes using passed in keys Returns undef if there is not difference, otherwise difference details.

format_values

Converts passed in list to string.

retrive_tables_data

Returns retrieved data for passed in tables

retrive_table_data

Returns retrieved data for passed in table.

primary_key_hash_value

Returns primary key values hash.

xml_dataset_handler

_exists_in_database

Check is rows exists in database. Takes table name, hash ref of field values, connection object

load_xml

Loads xml

_load_file_content

TODO

Extend detection for complex plsql blocks in the objects_to_create method.

COPYRIGHT AND LICENSE

The DBUnit module is free software. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

SEE ALSO

DBIx::Connection

AUTHOR

Adrian Witas, adrian@webapp.strefa.pl