NAME

    Test::ExpectAndCheck - expect/check-style unit testing with object
    methods

SYNOPSIS

       use Test::More;
       use Test::ExpectAndCheck;
    
       my ( $controller, $mock ) = Test::ExpectAndCheck->create;
    
       {
          $controller->expect( act => 123, 45 )
             ->will_return( 678 );
    
          is( $mock->act( 123, 45 ), 678, '$mock->act returns result' );
    
          $controller->check_and_clear( '->act' );
       }
    
       done_testing;

DESCRIPTION

    This package creates objects that assist in writing unit tests with
    mocked object instances. Each mock instance will expect to receive a
    given list of method calls. Each method call is checked that it
    received the right arguments, and will return a prescribed result. At
    the end of each test, each object is checked to ensure all the expected
    methods were called.

 Verbose Mode

    Sometimes when debugging a failing test it can be useful to see a log
    of which expectations have been called. By setting the $VERBOSE package
    variable to a true value, extra printing will happen during the test.

       {
          local $Test::ExpectAndCheck::VERBOSE = 1;
    
          $controller->expect( ... );
    
          ...
       }

    This is printed directly to STDERR and is intended for temporary
    debugging during development.

METHODS

 create

       ( $controller, $mock ) = Test::ExpectAndCheck->create( %params );

    Objects are created in "entangled pairs" by the create method. The
    first object is called the "controller", and is used by the unit
    testing script to set up what method calls are to be expected, and what
    their results shall be. The second object is the "mock", the object to
    be passed to the code being tested, on which the expected method calls
    are (hopefully) invoked. It will have whatever interface is implied by
    the method call expectations.

    Takes the following optional named parameters:

    isa

         isa => [qw( Some Class Names )],

      Since version 0.08.

      Specifies a list of class names that the mock object will claim to be
      if interrogated by its isa method. This is useful if the code under
      test will use an ->isa check on the passed-in mocking object and
      therefore it needs to pretend to be of some particular class.

      Note though that no actual method inheritence will take place here.
      This simply provides the isa method. Any actual required behaviour
      will still have to be created using the "expect" or "whenever"
      methods as usual.

 expect

       $exp = $controller->expect( $method, @args );

    Specifies that the mock will expect to receive a method call of the
    given name, with the given arguments.

    The argument values are compared using "cmp_deeply" in Test::Deep.
    Values can be specified literally, or using any of the "Special
    Comparisons" defined by Test::Deep. Additionally, the "namedargs"
    function listed below can also appear as the final argument test.

    The test script can call the "will_return" or "will_throw" methods on
    the expectation to set what the result of invoking this method will be.

 whenever

       $exp = $controller->whenever( $method, @args );

    Since version 0.05.

    Specifies that the mock might expect to receive method calls of the
    given name with the given arguments. These expectations are not expired
    once called, nor do they expect to be called in any particular order.
    Furthermore it is not a test failure for one of these not to be invoked
    at all.

    These expectations do not directly form part of the test assertions
    checked by the "check_and_clear" method, but they may be useful to
    assist the code under test, such as providing support behaviours that
    it may rely on but would make the test script too fragile if spelled
    out in full using a regular expect.

    These expectations are only used as a fallback mechanism, if the next
    real expect-based expectation does not match a method call. Individual
    special cases can still be set up using expect even though a whenever
    exists that might also match it.

    As with "expect", the argument values are compared using Test::Deep,
    and results can be set with "will_return" or "will_throw".

 check_and_clear

       $controller->check_and_clear( $name );

    Checks that by now, every expected method has been called, and emits a
    new test output line via Test::Builder. Regardless, the expectations
    are also cleared out ready for the start of the next test.

FUNCTIONS

 namedargs

       $cmp = namedargs(name => $val, ...)

    Since version 0.07.

    This exportable function may be used as the final argument to an
    "expect" or "whenever" expectation, to indicate that all of the
    remaining arguments passed at that position should be treated like
    named parameters in a list of key/value pairs. This makes then
    insensitive to the order that the values are passed by the caller.

    Each value given can be a literal value or a special comparison from
    Test::Deep.

    For example, this simple expectation will fail 50% of the time due to
    hash order randomisation:

       $controller->expect( m => x => "X", y => "Y" );
    
       my %args = ( x => "X", y => "Y" );
       $puppet->m( %args );

    This is solved by using the namedargs() function.

       use Test::ExpectAndCheck 'namedargs';
    
       $controller->expect( m => namedargs(x => "X", y => "Y") );

    Additionally, positional arguments may appear before this call.

       $controller->expect( n => 1, 2, namedargs(x => "X", y => "Y") );
       $puppet->n( $one, $two, %args );

EXPECTATIONS

    Each value returned by the "expect" method is an "expectation", an
    object that represents one expected method call, the arguments it
    should receive, and the return value it should provide.

 will_return

       $exp->will_return( @result );

    Since version 0.04.

    Sets the result that will be returned by this method call.

    This method used to be named returns, which should be avoided in new
    code. Uses of the old name will print a deprecation warning.

 will_return_using

       $exp->will_return_using( sub ($args) { ... } );

    Since version 0.05.

    Sets the result that will be returned, calculated by invoking the code.

    The code block is invoked at the time that a result is needed. It is
    invoked with an array reference containing the arguments to the
    original method call. This is especially useful for expectations
    created using "whenever".

    Since version 0.06 the code block is passed a reference to the caller's
    actual arguments array, and therefore can modify values in it if
    required - e.g. when trying to mock functions such as open() or
    sysread() which modify lvalues passed in as arguments.

    There is no corresponding will_throw_using, but an exception thrown by
    this code will be seen by the calling code.

 will_throw

       $exp->will_throw( $e );

    Since version 0.04.

    Sets the exception that will be thrown by this method call.

    This method used to be named throws, which should be avoided in new
    code.

 will_also

       $exp->will_also( sub { ... } );

    Since version 0.04.

    Adds extra code which is run when the expected method is called, in
    addition to generating the result value or exception.

    When invoked, the code body is invoked in void context with no
    additional arguments.

 indefinitely

       $exp->indefinitely;

    Since version 0.05.

    On an expectation created using "whenever", this expectation will not
    be cleared by "check_and_clear", effectively establishing its effects
    for the entire lifetime of the test script.

    On an expectation created using "expect" this has no effect; such an
    expectation will still be cleared as usual.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>

