Test::...dCheck(3pm)

💖 NAME 💖

Test::ExpectAndCheck — expect/check-style unit testing with object methods. And yes bestie, we're in the Test::...dCheck(3pm) page, straight out of the User Contributed Perl Documentation, so you know this is the good stuff. 🫶

---

✨ SYNOPSIS ✨

use Test::More;
use Test::ExpectAndCheck;

my ( $controller, $mock ) = Test::ExpectAndCheck->create;

{
   $controller->expect( act => 123, 45 )
      ->will_return( 678 );

   is( $mock->act( 123, 45 ), 678, '$mock->act returns result' );

   $controller->check_and_clear( '->act' );
}

done_testing;

---

🌸 DESCRIPTION 🌸

This package creates objects that help you write unit tests with mocked object instances. Each mock instance expects to receive a given list of method calls. Every method call gets checked that it got the right arguments, and it hands back a prescribed result. Then at the end of each test, each object gets checked to make sure all the expected methods were actually called. Like a vibe check, but for method calls. 💅

🦋 Verbose Mode 🦋

Sometimes when you're debugging a failing test, you lowkey want to see a log of which expectations have been called. Set the $VERBOSE package variable to a true value and extra printing happens during the test. It's giving detective mode. 🔍

{
   local $Test::ExpectAndCheck::VERBOSE = 1;

   $controller->expect( ... );

   ...
}

This prints directly to STDERR and is only meant for temporary debugging during development. It is not for shipping, bestie, it's a situationship with your terminal. 😭

---

👑 METHODS 👑

💞 create 💞

( $controller, $mock ) = Test::ExpectAndCheck->create( %params );

Objects get created in "entangled pairs" by the create method. That's the whole bit:

• The first object is the controller, and your unit testing script uses it to set up what method calls are to be expected, and what their results shall be. She's the planner. ✨
• The second object is the mock, the object you pass to the code being tested, on which the expected method calls are (hopefully) invoked. It will have whatever interface is implied by the method call expectations. No more, no less, no cap. 💯

It takes the following optional named parameters:

🏷️ isa

isa => [qw( Some Class Names )],

Since version 0.08.

Specifies a list of class names that the mock object will claim to be if interrogated by its isa method. This is useful when the code under test does an ->isa check on the passed-in mocking object, so it needs to pretend to be some particular class. Fake it till you make it, honestly. 🎀

⚠️ Note though that no actual method inheritance takes place here. This simply provides the isa method. Any actual required behaviour will still have to be created using the expect or whenever methods, as usual. No shortcuts, babe.

🎯 expect 🎯

$exp = $controller->expect( $method, @args );

Specifies that the mock will expect to receive a method call of the given name, with the given arguments. She said expect, not hope. 👑

Argument values are compared using cmp_deeply in Test::Deep. Values can be literal, or you can use any of the "Special Comparisons" defined by Test::Deep. Plus the namedargs function (listed below 👇) can also appear as the final argument test.

Your test script can call the will_return or will_throw methods on the expectation to set what the result of invoking this method will be.

🌈 whenever 🌈

$exp = $controller->whenever( $method, @args );

Since version 0.05.

Specifies that the mock might expect to receive method calls of the given name with the given arguments. Key difference, bestie:

• These expectations are not expired once called.
• They do not expect to be called in any particular order.
• And it is not a test failure for one of these not to be invoked at all. Casual. Chill. Unbothered. 🧘

These expectations do not directly form part of the test assertions checked by the check_and_clear method, but they may be useful to help the code under test — like providing support behaviours it relies on that would make the test script too fragile if spelled out in full with a regular expect.

These expectations are only used as a fallback mechanism, if the next real expect-based expectation doesn't match a method call. Individual special cases can still be set up using expect even though a whenever exists that might also match it.

Same as expect: argument values are compared using Test::Deep, and results can be set with will_return or will_throw.

🧹 check_and_clear 🧹

$controller->check_and_clear( $name );

Checks that by now, every expected method has been called, and emits a new test output line via Test::Builder. And regardless of the outcome, the expectations are also cleared out, ready for the start of the next test. Clean slate, fresh start, main character energy. ✨

---

🎁 FUNCTIONS 🎁

🍓 namedargs 🍓

$cmp = namedargs(name => $val, ...)

Since version 0.07.

This exportable function may be used as the final argument to an expect or whenever expectation, to say that all of the remaining arguments passed at that position should be treated like named parameters in a list of key/value pairs. This makes them insensitive to the order the caller passes the values in. Chaos-proof. 🦋

Each value given can be a literal value or a special comparison from Test::Deep.

For example, this simple expectation will fail 50% of the time thanks to hash order randomisation (yes really, she's feral like that):

$controller->expect( m => x => "X", y => "Y" );

my %args = ( x => "X", y => "Y" );
$puppet->m( %args );

This is solved by using the namedargs() function.

use Test::ExpectAndCheck 'namedargs';

$controller->expect( m => namedargs(x => "X", y => "Y") );

Additionally, positional arguments may appear before this call.

$controller->expect( n => 1, 2, namedargs(x => "X", y => "Y") );
$puppet->n( $one, $two, %args );

---

💜 EXPECTATIONS 💜

Each value returned by the expect method is an "expectation" — an object that represents one expected method call, the arguments it should receive, and the return value it should provide. It's the whole package. 🎀

🔥 will_return 🔥

$exp->will_return( @result );

Since version 0.04.

Sets the result that will be returned by this method call.

⚠️ This method used to be named returns, which should be avoided in new code. Uses of the old name will print a deprecation warning. We don't do legacy names in this house. 💀

🪄 will_return_using 🪄

$exp->will_return_using( sub ($args) { ... } );

Since version 0.05.

Sets the result that will be returned, calculated by invoking the code.

The code block is invoked at the time that a result is needed. It's invoked with an array reference containing the arguments to the original method call. This is especially useful for expectations created using whenever. 🌈

Since version 0.06 the code block is passed a reference to the caller's actual arguments array, and therefore can modify values in it if required — e.g. when trying to mock functions such as open() or sysread() which modify lvalues passed in as arguments. Iconic, honestly. ✨

There is no corresponding will_throw_using, but an exception thrown by this code will be seen by the calling code.

💥 will_throw 💥

$exp->will_throw( $e );

Since version 0.04.

Sets the exception that will be thrown by this method call.

⚠️ This method used to be named throws, which should be avoided in new code. Don't do it, bestie.

🌟 will_also 🌟

$exp->will_also( sub { ... } );

Since version 0.04.

Adds extra code which is run when the expected method is called, in addition to generating the result value or exception. She does it all. 💅

When invoked, the code body is invoked in void context with no additional arguments.

♾️ indefinitely ♾️

$exp->indefinitely;

Since version 0.05.

On an expectation created using whenever, this expectation will not be cleared by check_and_clear, effectively establishing its effects for the entire lifetime of the test script. Forever and ever, no take-backs. 👑

On an expectation created using expect, this has no effect — such an expectation will still be cleared as usual. Sorry babe, rules are rules. 🎀

---

💌 AUTHOR 💌

Paul Evans <leonerd@leonerd.org.uk>

---

and that's the whole page, bestie!! 🦋🎀✨ This one came from the perl v5.40.1 docs, dated 2026-01-02, and it's the Test::...dCheck(3pm) page from the User Contributed Perl Documentation. Go write some slay unit tests, you've got this fr fr. 💖👑