NAME

       Test::DatabaseRow::Object - examine database rows

SYNOPSIS

         use Test::More tests => 1;
         use Test::DatabaseRow::Object;

         # setup the test
         my $tdr = Test::DatabaseRow::Object->new(
           sql_and_bind => "SELECT * FROM contacts WHERE cid = '123'",
           tests        => [ name => "trelane" ],
         );

         # do the test and get a result back
         my $result_object = $tdr->tests_ok();

         # have those results render to Test::Builder
         $result_object->pass_to_test_builder("my database test");

DESCRIPTION

       This module provides the underlying functionality of "Test::DatabaseRow".

   Accessors
       These are the read only accessors of the object.  They may be (optionally) set at object
       creation time by passing their name and value to the constructor.

       Each accessor may be queried by prefixing its name with the "has_" to determine if it has
       been set or not.

       db_results
           An arrayref of hashrefs, each representing a row returned from the database.  Each key
           in the hashref should be the column name and the value the corresponding field's
           value.  This datastructure is identical to that.

           If this accessor is not passed then it will be populated on first use by executing the
           contents of "sql_and_bind" against the passed "dbh".

       db_results_dumped
           A string representation of the database results.

           If this accessor is not passed then it will be populated on first use by using
           Test::Builder's explain function on "db_results"

       sql_and_bind
           The SQL and bind variables to execute if no results were passed into the db_results
           hash.  This should be an arrayref containing the SQL as the first element and the bind
           values as further values.

           This accessor will automatically coerce a simple scalar passed in into a single

           If this accessor is not passed then it will be populated on first use by building SQL
           from the "where" and "table" accessors.

       dbh The database handle used to execute the SQL statement in "sql_and_bind" if no
           "db_results" were passed.

       table
           The table name used to build the SQL query if no value is passed to "sql_and_bind".
           String.

       where
           The data structure used to build the where clause of the SQL query if no value is
           passed to <sql_and_bind>.

           This accessor value should be a hashref of hashrefs, with the outer keys being the SQL
           comparison operator, the inner keys being the field names and the inner values being
           the values to match against. For example:

             {
               '='    => { first => "Fred", last => "Flintstone", },
               'like' => { address => "%Bedrock%" },
             }

           Values of "undef" will automatically converted into checks for NULLs.

           This accessor automatically coerces array refs that are passed into a pure equals
           hashref.  For example:

             [ foo => "bar", bazz => "buzz" ]

           Will be coerced into:

             { "=" => { foo => "bar", bazz => "buzz" } }

           See "where" in Test::DatabaseRow for a more detailed explanation.

       verbose
           Truth value, default false.  Controls if the diagnostic messages printed during
           "row_ok" on failure contain details of the SQL executed or not.

       verbose_data
           Truth value, default false.  Controls if the diagnostic messages printed during
           "row_ok" on failure contain a Data::Dumper style dump of the resulting rows from the
           database.

       force_utf8
           Truth value, default false.  Controls if the utf8 flag should be turned on on values
           returned from the database.  See "utf8 hacks" in Test::DatabaseRow for why this might
           be important.

           This flag only effects data that this module places into "db_resutls".  If you
           manually populate this accessor this flag will have no effect.

       tests
           If set, enables specified tests on the first element of "db_results" when "row_ok" is
           called.

           This accessor value should be a hashref of hashrefs, with the outer keys being the
           Perl comparison operator, the inner keys being the field names and the inner values
           being the values to test against. For example:

             {
               'eq' => { first => "Fred", last => "Flintstone", },
               '=~' => { address => "%Bedrock%" },
             }

           This accessor automatically coerces array refs that are passed into a hashref
           structure, converting things that look like strings into "eq" tests, things that look
           like numbers into "==" tests and things that are references to regular expressions
           into "=~" tests.  Foe example:

             [ num => 123, letters => "abc", kinda => qr/substring/ ]

           Will be coerced into

             {
               '==' => { num => 123, },
               'eq' => { letters => "abc", },
               '=~' => { kinda => qr/substring/ },
             }

           See "tests" in Test::DatabaseRow for a more detailed explanation.

       check_all_rows
           Boolean to determine if we should test all rows (during "db_results_ok" and "test_ok")
           or just check the first row.  Default true.

       results
           If set, enable tests to check the number of rows we returned by "db_results" is
           exactly this value when "row_ok" is called.  Integer.

       max_results
           If set, enable tests to check the number of rows we returned by "db_results" is at
           most this value when "row_ok" is called.  Integer.

       min_results
           If set, enable tests to check the number of rows we returned by "db_results" is at
           least this value when "row_ok" is called.  Integer.

   Methods
       new(...)
           Simple constructor.  Passing arguments to the constructor sets the values of the
           accessors.

       number_of_results_ok
           Returns a Test::DatabaseRow::Result that represents if the number of results in
           "db_results" match the requirements for the number of results.

       row_at_index_ok( $row_index )
           Returns a Test::DatabaseRow::Result that represents if the element corresponding to
           the passed row index in "db_results" match the tests defined in "tests".

       db_results_ok
           Returns a Test::DatabaseRow::Result that represents if all elements in "db_results"
           match the tests defined in "tests".

       test_ok
           Returns a Test::DatabaseRow::Result that represents if the number of results in
           "db_results" match the requirements for the number of results and  all elements in
           "db_results" match the tests defined in "tests".

BUGS

       Bugs (and requests for new features) can be reported though the CPAN RT system:
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-DatabaseRow>

       Alternatively, you can simply fork this project on github and send me pull requests.
       Please see <http://github.com/2shortplanks/Test-DatabaseRow>

AUTHOR

       Written by Mark Fowler mark@twoshortplanks.com

       Copyright Profero 2003, 2004.  Copyright Mark Fowler 2011.

       Some code taken from Test::Builder, written by Michael Schwern.  Some code taken from
       Regexp::Common, written by Damian Conway.  Neither objected to its inclusion in this
       module.

       Some code taken from Lingua::EN::Numbers::Ordinate, written by Sean M. Burke.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       Test::DatabaseRow::Object, Test::DatabaseRow::Result, Test::More, DBI