NAME
    Test::Shadow - override a class's methods in a scope, checking
    input/output

SYNOPSIS
    Provides RSpec-like mocking with 'receive'/'and_return' functionality.
    However the interface is more explicit. This may be considered a
    feature.

        use Test::More;
        use Test::Shadow;

        use Foo;

        with_shadow Foo => inner_method => {
            in => [ 'list', 'of', 'parameters' ],
            out => 'barry',
            count => 3
        }, sub {
            my $foo = Foo->new;
            $foo->outer_method();
        };

EXPORTED FUNCTIONS
  with_shadow
    Exported by default

        with_shadow $class1 => $method1 => $args1, ..., $callback;

    Each supplied class/method is overridden as per the specification in the
    supplied args. Finally, the callback is run with that specification.

    The args passed are as follows:

    in  A list of parameters to compare every call of the method against.
        This will be checked each time, until the first failure, if any. The
        parameters can be supplied as an arrayref:

            in => [ 'list', 'of', 'parameters' ]

        or a hashref:

            in => { key => 'value', key2 => 'value2 },

        and the comparison may be made using any of the extended routines in
        Test::Deep

            use Test::Deep;
            with_shadow Foo => inner_method => {
                in => { foo => any(1,2,3) },
                ...

    out Stub the return value. This can be

        *   a simple (non-reference) scalar value

                ...
                out => 100,

        *   a subroutine ref, which will be passed at every invocation the
            parameters "($orig, $self, @args)".

        Note that the subroutine args are the same as if you were creating a
        Moose or Class::Method::Modifiers "around" wrapper, but dynamically
        scoped to the test.

            out => sub { my ($orig, $self, @args) = @_; ... },

        If you want to return a reference (including a subroutine reference)
        return this from the subroutine: We require wrapping in a subroutine
        ref for the same reason that Moose's "default" does: otherwise we
        would end up passing the same reference to each invocation, with
        possibly surprising results.

            out => sub { [] }, # return a new, empty arrayref on each invocation

        Of course you can simply ignore the call args and invoke as a
        subroutine. See also the "iterate" function.

    count
        The number of times you expect the method to be called. This is
        checked at the end of the callback scope.

        This may be an exact value:

            count => 4,

        Or a hashref with one or both of "min" and "max" declared:

            count => { min => 5, max => 10 },

  iterate
    We provide a helper function to iterate over a number of scalar return
    values. This can be attached to "out", and takes a list of values to be
    provided as the stubbed return value on each successive call.

        use Test::Shadow 'iterate';

        with_shadow ...
            out => iterate(1,2,3,4), # return 1 on first invocation, 2 on second, etc.
            ...

    The values wrap if they run out: you may want to use a "count" argument
    to diagnose that this has happened.

    As well as simple values, "iterate" handles method calls in exactly the
    same format as they are normally passed to "out".

        with_shadow ...
            out => iterate(
                sub { my ($orig, $self, $arg) = @_; ... },
                ...

SEE ALSO
    There are several other modules that deal with mocking objects. One of
    them may well serve your needs better. I was having RSpec envy, about
    the call expectation side of things (not about the "English-like" DSL,
    which I found both confusing, and slightly filthy) so Test::Shadow is
    designed to cover that use case with an API that is less magical and
    more Perlish (thanks to ribasushi, haarg, tobyink, vincent, ether on
    #perl-qa for pointing out that my first implementation with the
    lovely-but-frightening Scope::Upper may not have been the poster child
    for sanity I'd intended.)

    *   Test::MockObject is the oldest CPAN library I'm aware of. It has a
        very different usage, where you create an *object instance* and stub
        methods on it, rather than mocking a class.

    *   Test::MockModule does mock a class's methods, but hasn't been
        updated since 2005, and doesn't give the control over return value
        stubbing and call count tracing.

    *   Mock::Quick looks like a more modern mocking implementation. Again,
        it looks like this works on an object instance.

    *   Test::Spec looks like a good reimplementation of RSpec, which means
        that personally I dislike aspects of the API -- the monkey-patching
        and the confusing "expects" and "returns" keywords, but this may be
        a good choice. Note that the ::Mocks routines are "currently only
        usable from within tests built with the Test::Spec BDD* framework".

    * my current (snarky) understanding is that "BDD" means something to do
    with using "it" and "describe" as synonyms for "subtest".

AUTHOR and LICENSE
    Copyright 2014 Hakim Cassimally <osfameron@cpan.org>

    This module is released under the same terms as Perl.