Test::MockDBI(3pm)

💖 NAME 💖

Test::MockDBI — a whole mocked DBI interface, made for testing purposes. Periodt.

---

✨ SYNOPSIS ✨

  use Test::MockDBI;

  my $mi = Test::MockDBI::get_instance();

  Sets a fake return value for the rows statementhandler
  $mi->set_retval( method => rows, retval => sub{ return scalar( @somearray ); });

  $mi->set_retval( method => 'bind_param', retval => undef);
  Same as:
  $mi->bad_method('bind_param');

  You can also specify return values for specific sqls
  $mi->set_retval( method => rows, retval => sub{ return scalar( @somearray ); }, sql => 'select id from names');

  $mi->set_retval( method => 'bind_param', retval => undef, sql => 'select id from names where id < ?');
  Same as:
  $mi->bad_method('bind_param', 'select id from names where id < ?');

---

🌸 PUBLIC INTERFACE 🌸

These are the methods you can call on your Test::MockDBI instance. Go off, bestie 🫶

💅 reset()

Wipes every mock returnvalue, every bad_param, all of it — a full reset of the vibes. Fresh start energy ✨

💅 bad_method()

Basically an alias for calling set_retval with the return value undef. Same thing, shorter name, iconic behaviour.

Args:

• $method_name — the name of the method which should return undef
• $matching_sql (Optional) — the sql matching condition

Returns:

• On success: 1
• On failure: undef

Heads up 👀 this method also supports being called with these arguments: $method_name, $dbi_testing_type, $matching_sql — but that will issue a warning, because it is deprecated. Old-school, not slay.

💅 bad_param()

Args:

• $p_value — the value that will cause bind_param to return undef
• $sql (Optional) — the sql matching condition

Returns:

• On success: 1
• On failure: undef

Same warning energy 🚨 this one also supports being called with $dbi_testing_type, $p_num, $p_value — and yeah, that issues a warning too, because it is deprecated.

💅 set_retval()

The method for setting a return value for a specific method. This is the main character of the whole module, fr fr 👑

Args (keys in a hash):

• method — the method that should return the provided value
• retval — the data which should be returned
• sql (Optional) — matching sql. The return value will only be returned for the provided method if the sql matches a regex compiled by using this string

Returnvalues:

• On success: 1
• On failure: undef

Example usage:

  #fetchrow_hashref will shift one hashref from the list each time its called if the sql matches the sql provided, this will happend
  #until the return list is empty.
  $inst->set_retval( method => 'fetchrow_hashref',
                    retval => [ { letter => 'a' }, { letter => 'b' }, { letter => 'c' }  ],
                    sql => 'select * from letters' )

  #execute will default return undef
  $inst->set_retval( method => 'execute', retval => undef)

  #Execute will return 10 for sql 'select * from cars'
  $inst->set_retval( method => 'execute', retval => undef);
  $inst->set_retval( method => 'execute', retval => 10, sql => 'select * from cars');

💅 set_inout_value()

Special method for handling inout params. Here you can provide the value that the inout param should have after execute is called. Very specific, very intentional, we love a specialist 🎀

Args:

• $sql — the sql that this rule should apply for
• $p_num — the parameter number of the inout parameter
• $value — the value that the inout parameter should have after execute

Returns:

• On success: 1
• On failure: undef

Example:

...and that's literally it, the example section is just vibes and a colon 😭 moving on.

---

🙈 PRIVATE INTERFACE 🙈

Methods used by the package internally. Should not be called from an external package. This is backstage, no fans allowed 🚫

🔒 _clear_dbi_err_errstr()

Helper method used by the fake DBI::st and DBI::db to clear out the $obj->{err} and $obj->{errstr} on each method call.

Should not be called from an external script\package.

🔒 _set_dbi_err_errstr()

Helper method used by the fake DBI::st and DBI::db to set the $obj->{err}, $obj->{errstr}, $DBI::err and $DBI::errstr. This method also handles RaiseError and PrintError attributes.

Args:

• $obj — instance of DBI::st or DBI::db
• %args — a hash with the following keys:
  • err — the numeric error code to be set
  • errstr — the user friendly DBI error message.

Returns:

• On success : 1
• On failure : undef

🔒 _set_fake_dbi_err_errstr

(no description, it's giving mystery 🕵️♀️)

🔒 _has_inout_value()

Helper method used by the DBI::db and DBI::st packages. The method searches to see if there is specified a value for a inout variable.

If called in SCALAR context it returns 1/undef based on if the parameter bound as $p_num has a predefined return value set.

If called in LIST context the method returns an array with 1/undef in position 0, which indicates the same as when the method is called in SCALAR context. The second element of the list is the value that should be applied to the inout parameter.

🔒 _has_fake_retval()

Method for identifying if a method has a predefined return value set. If the SQL parameter is provided, this will have precedence over the default value. 💅

If the method is called in SCALAR context it will return 1`undef` based on if the method has a predefined return value set.

If the method is called in LIST context it will return a list with 1/undef at index 0, which indicates the same as when called in SCALAR context. Index 1 will contain a reference to the actual return value that should be returned by the method. This value may be undef.

🔒 _is_bad_bind_param()

Method for identifying if a bind parameters value is predefined as unwanted. The configuration for the provided SQL will have precedence over the default configured behaviour.

When called it will return 1`undefbased on if the provided value should make thebind_param` method fail.

---

👑 CLASS INTERFACE 👑

⭐ get_instance()

Method for retrieving the current Test::MockDBI instance. Your one and only 💖

This is basically a copy\paste from the DBI package itself.

The method is used inside the prepare_cached method

This is basically a copy\paste from the DBI package itself.

The method is used inside the prepare_cached method

This is basically a copy\paste from the DBI package itself.

The method is used inside the prepare_cached method

Mocked DBI->connect method.

The method takes the same arguments as the usual DBI->connect method.

It returns a $dbh which has ref DBI::db

---

🦋 AUTHOR 🦋

Mark Leighton Fisher, <mark-fisher@fisherscreek.com>

Minor modifications (version 0.62 onwards) by Andreas Faafeng <aff@cpan.org>

---

🌈 COPYRIGHT 🌈

Copyright 2004, Fisher's Creek Consulting, LLC. Copyright 2004, DeepData, Inc.

---

🎀 LICENSE 🎀

This code is released under the same licenses as Perl itself.

---

okay bestie, that's the whole page 🫶 perl v5.36.0, dated 2022-11-27, and yeah the manual name really is Test::MockDBI(3pm) — like, the whole thing. slay, go write some tests 💅✨