NAME

Test::Magpie - Mocking framework with method stubs and behaviour verification

SYNOPSIS

    use Test::Magpie;

    # create the mock object and stub
    my $baker = mock;
    when($mock)->bake_loaf('white')->then_return($bread);

    # execute the code under test
    my $bakery = Bakery->new( bakers => [ $baker ] );
    my @loaves = $bakery->buy_loaf( amount => 2, type => 'white' );

    # verify the interactions with the mock object
    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.

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.

Method stubbing

Any method can be called on a mock object, and it will be logged as an invocation. By default, method calls return undef in scalar context or an empty list in list context. Often, though, clients will be interested in the result of calling a method with some arguments. So you may specify how a method stub should respond when it is called.

Verify interactions

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

mock() constructs a new instance of a mock object.

    $mock = mock;
    $mock->method(@args);

$class is an optional argument to set the type that the mock object is blessed into. This value will be returned when ref() is called on the object.

    $mock = mock($class);
    is( ref($mock), $class );

when

when() is used to tell the method stub to return some value(s) or to raise an exception.

    when($mock)->method(@args)->then_return(1, 2, 3);
    when($mock)->invalid(@args)->then_die('exception');

verify

verify() is used to check the interactions on your mock object and prints the test result. verify() plays nicely with Test::Simple and Co - it depends on them for setting a test plan and its calls are counted in the test plan.

    verify($mock)->method(@args)
    # prints: ok 1 - method("foo") was called 1 time(s)

verify() accepts an optional $test_name to print a custom name for the test instead of the default.

    verify($mock, $test_name)->method(@args)
    # prints: ok 1 - record inserted into database'

verify() accepts a few options to help your verifications:

    verify( $mock, times    => 3,     )->method(@args)
    verify( $mock, at_least => 3      )->method(@args)
    verify( $mock, at_most  => 5      )->method(@args)
    verify( $mock, between  => [3, 5] )->method(@args)

times

Specifies the number of times the given method is expected to be called. The default is 1 if no other option is specified.

at_least

Specifies the minimum number of times the given method is expected to be called.

at_most

Specifies the maximum number of times the given method is expected to be called.

between

Specifies the minimum and maximum number of times the given method is expected to be called.

A $test_name may also be supplied after the option.

    verify($mock, times => 3, $test_name)->method(@args)

inspect

Inspect method invocations on a mock object.

    $invocation = inspect($mock)->method(@args);
    is( $invocation->method_name, 'foo' );
    is_deeply( [$invocation->arguments], [qw( bar baz )] );

at_least (deprecated)

Used with verify() to verify that a method was invoked at least $n times.

    verify($mock, times => at_least($n))->method(@args);

This function has been deprecated. Use the at_least option for verify() instead.

at_most (deprecated)

Used with verify() to verify that a method was invoked at most $n times.

    verify($mock, times => at_most($n))->method(@args);

This function has been deprecated. Use the at_most option for verify() instead.

EXPORTS

This module exports the following functions by default:

• mock

• when

• verify

All other functions need to be imported explicitly.

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.

cpanm Test::Magpie

perl -MCPAN -e shell
install Test::Magpie