Test::M...tMatcher(3)

💅 Test::Magpie::ArgumentMatcher 💅

okay so bestie, you're looking at Test::Magpie::ArgumentMatcher, from the User Contributed Perl Documentation crew — and it is literally the most iconic little toolkit for catching arguments in your mocks. periodt.

---

✨ NAME ✨

Test::Magpie::ArgumentMatcher — various templates to catch arguments 🎀

---

🌸 SYNOPSIS 🌸

use Test::Magpie;
use Test::Magpie::ArgumentMatcher qw( anything );

my $mock = mock;
$mock->push( button => 'red' );

verify($mock)->push(anything);

---

🦋 DESCRIPTION 🦋

So here's the vibe: argument matchers let you be all chill and general when you're setting up specs for stubs and verification. No need to pin down every single arg, bestie.

An argument matcher is an object that grabs all the remaining parameters of an invocation, eats 1 or more of them, and hands the leftover arguments back to you. Then at verification time? An invocation gets verified only if every argument has been nommed by all the argument matchers. That's the whole game. 👑

One lil thing to know: an argument matcher may return undef if the argument does not pass validation. Rude, but fair. 💀

🧚 Custom argument validators

An argument validator is honestly just a subroutine that's been blessed as Test::Magpie::ArgumentMatcher. That's it. You are super welcome to subclass this package if you wanna use a different storage system (like, say, a traditional hash-reference) — but ngl, a single subroutine is normally all you will need. 🫶

🍓 Default argument matchers

This module comes with a whole set of common argument matchers preloaded, and they will probably handle most of your needs. They're all available for import by name, so go off. ✨

---

💜 METHODS 💜

• match @in — matches an argument matcher against @in, and returns a list of parameters still to be consumed. Or undef on validation. Simple as that.

---

🔥 FUNCTIONS 🔥

• anything — consumes all remaining arguments (even 0 of them, bestie) and returns none. It effectively slurps up any remaining arguments and declares them valid. 🌈 Heads up though: since this one consumes everything, you cannot use further argument validators after it. But you are, however, more than welcome to use them before. So order matters, iykyk.
• custom_matcher { ...code.... } — creates a custom argument matcher just for you. 💖 This argument matcher is assumed to be the final argument matcher. If it passes (that is, returns a true value), then it's assumed that all remaining arguments have been matched. Custom matchers are code references. You can use $_ to reference the first argument, but a custom argument matcher may match more than one argument. In essence, it's passed the contents of @_ that have not yet been matched. 🎀
• type $type_constraint — checks that a single value meets a given Moose type constraint. You might wanna consider the use of MooseX::Types here for code clarity, just saying. 🦋
• hash %match — does deep comparison on all remaining arguments, and verifies that they meet the specification in %match. ⚠️ Note that this is for hashes, not hash references! Don't come for me, I'm just the messenger. 😭
• set @values — compares that all remaining arguments match the set of values in @values. This lets you compare objects out of order, which is honestly iconic. 👑

Note: this currently uses real Set::Objects to do the work, which means duplicate arguments are ignored. For example, 1, 1, 2 will match 1, 2, 1, 2, 2. This is probably a bug and it will get fixed, but for now the author's mostly waiting for a bug report — sorry! 🙈

---

👑 AUTHORS 👑

• Oliver Charles <oliver.g.charles@googlemail.com>
• Steven Lee <stevenwh.lee@gmail.com>

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2013 by Oliver Charles.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

---

⭐ mwah, that's the whole page ⭐ — perl v5.42.0, dated 2020-11-24, and this lil manual page is officially a wrap. stay slaying, bestie 💅✨