NAME

Test::Magpie - Spy on objects to achieve test doubles (mock testing)

SYNOPSIS

    use Test::Magpie qw( mock verify when );

    my $baker = mock;
    my $bakery = Bakery->new( bakers => [ $baker ] );
    my $bread = $bakery->buy_loaf( amount => 2, type => 'white' );
    verify($baker, times => 2)->bake_loaf('white');

DESCRIPTION

Test::Magpie is a test double framework heavily inspired by the Mockito framework for Java, and also the Python-Mockito project. In Mockito, you "spy" on objects for their behaviour, rather than being upfront about what should happen. I find this approach to be significantly more flexible and easier to work with than mocking systems like EasyMock, so I created a Perl implementation.

Test::Magpie doesn't do much, but it does export the main routines that you use to interact with the framework.

Mock objects

Mock objects, represented by Test::Magpie::Mock objects, are objects that pretend to be everything you could ever want them to be. A mock object can have any method called on it, does every roles, and isa subclass of any superclass. This allows you to easily throw a mock object around it will be treated as though it was a real object.

Methods and stubbing

Any method can be called on a mock object, and it will be logged as an invocation. Most often though, clients will be more interested in the result of calling a method with some arguments, so you may stub methods in order to specify what happens at execution.

Verification

After calling your concrete code (the code under test) you may want to check that the code did operate correctly on the mock. To do this, you can use verifications to make sure code was called, with correct parameters and the correct amount of times.

Argument matching

Magpie gives you some helpful methods to validate arguments passed in to calls. You can check equality between arguments, or consume a general type of argument, or consume multiple arguments. See Test::Magpie::ArgumentMatcher for the juicy details.

FUNCTIONS

mock

Construct a new instance of a mock object.

verify($mock, [%options])

Begin the verification process on a mock. Takes a mock object, and gives back a Test::Magpie::Spy. You don't really need to be concerned about the API of this object, you should treat it as the same as the mock object itself. Any method calls trigger verification that the given method was passed, and will fail if the method was never invoked on the mock object.

%options contains a few nice options to help make verification easier:

times

Makes sure that the given method was called times times. This may either be an integer, or it could be a bit more general, and specified using "at_least" in Test::Magpie or "at_most" in Test::Magpie

when($mock)

Specify a stub method for $mock.

Returns an object that should be treated the same as $mock (that is, having all the same methods), but a method call stores a stub method in the mock class, rather than an invocation. After specifying the method you wish to stub, you will be working with a Test::Magpie::Stub, and you should consult that documentation for how to fully specify the stub.

inspect($mock)

Inspect method invocations on a mock object. See Test::Magpie::Inspect for more information.

at_least(Int $n)

Verify that a method was invoked at least $n times

at_most(Int $n)

Verify that a method was invoked at most $n times

AUTHOR

Oliver Charles

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Oliver Charles <oliver.g.charles@googlemail.com>.

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

cpanm Test::Magpie

perl -MCPAN -e shell
install Test::Magpie