Test::...:Object(3pm)

💖 NAME 💖

Test::DatabaseRow::Object — examine database rows 🔍✨

okay so first things first, bestie: this page is Test::DatabaseRow::Object(3pm) from the User Contributed Perl Documentation, and it's literally all about peeking at rows that came back from your database. no cap. 🫶

---

🌸 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");

like, look at that. setup, run the test, get a result object back, hand it to Test::Builder. chef's kiss. 👑

---

✨ DESCRIPTION ✨

This module provides the underlying functionality of Test::DatabaseRow. it's the engine room, the behind-the-scenes girly, the one doing the actual work. 💅

🎀 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. so has_whatever is your vibe check for "did this thing get set?" 🕵️‍♀️

• 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. lazy loading but make it fashion. ✨

• 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. it's giving "just tell me what you want and i'll handle it." 💅
• 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. the whole package deal fr fr. 🎀

---

😭 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

not me telling you to just fork it and send a PR, but honestly? iconic behaviour. 💅

---

👑 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

---

and that's the whole thing bestie!! this page is from perl v5.34.0, dated 2022-06-17, and it ate, no crumbs. go forth and test your database rows. 🦋💖✨🎀