The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Magpie-0.11
River stage zero No dependents
++
/ Test::Magpie::ArgumentMatcher

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

Argument matchers allow you to be more general in your specification to stubs and verification. An argument matcher is an object that takes all remaining paremeters of an invocation, consumes 1 or more, and returns the remaining arguments back. At verification time, a invocation is verified if all arguments have been consumed by all argument matchers.

An argument matcher may return undef if the argument does not pass validation.

Custom argument validators

An argument validator is just a subroutine that is blessed as Test::Magpie::ArgumentMatcher. You are welcome to subclass this package if you wish to use a different storage system (like a traditional hash-reference), though a single sub routine is normally all you will need.

Default argument matchers

This module provides a set of common argument matchers, and will probably handle most of your needs. They are all available for import by name.

METHODS

match @in

Match an argument matcher against @in, and return a list of parameters still to be consumed, or undef on validation.

FUNCTIONS

anything

Consumes all remaining arguments (even 0) and returns none. This effectively slurps in any remaining arguments and considers them valid. Note, as this consumes all arguments, you cannot use further argument validators after this one. You are, however, welcome to use them before.

custom_matcher { ...code.... }

Creates a custom argument matcher for you. This argument matcher is assumed to be the final argument matcher. If this matcher passes (that is, returns a true value), then it is assumed that all remaining arguments have been matched.

Custom matchers are code references. You can use $_ to reference to the first argument, but a custom argument matcher may match more than one argument. It is passed the contents of @_ that have not yet been matched, in essence.

type $type_constraint

Checks that a single value meets a given Moose type constraint. You may want to consider the use of MooseX::Types here for code clarity.

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!

set @values

Compares that all remaining arguments match the set of values in @values. This allows you to compare objects out of order.

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 I will fix it, but for now I'm 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.