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".

       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.

       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
       <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

perl v5.14.2                                       2011-12-07                     Test::DatabaseRow::Object(3pm)