NAME

       "Test::ExpectAndCheck::Future" - "expect/check"-style unit testing with "Future"-returning
       methods

SYNOPSIS

          use Test::More;
          use Test::ExpectAndCheck::Future;

          use Future::AsyncAwait;

          my ( $controller, $mock ) = Test::ExpectAndCheck::Future->create;

          {
             $controller->expect( act => 123, 45 )
                ->will_done( 678 );

             is( await $mock->act( 123, 45 ), 678, '$mock->act yields result' );

             $controller->check_and_clear( '->act' );
          }

          done_testing;

DESCRIPTION

       This package creates objects that assist in writing unit tests with mocked object
       instances. Each mocked 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 Future
       instance to yield the prescribed result. At the end of each test, each object is checked
       to ensure all the expected methods were called.

       It is a variation of Test::ExpectAndCheck, assistance around the results of invoked
       methods. Every invoked method will return a Future instance. The "will_done" or
       "will_fail" method can then set the desired eventual result of that future instance for
       each expectation.

       These return instances are implemented using Test::Future::Deferred, so they are not
       immediately ready. Instead they will only become ready after a toplevel "await" expression
       or call to the "get" method. This should help unit tests to run similarly to real-world
       behaviour, where most futures returned by real-world interfaces (such as IO systems) would
       not be immediately ready. This behaviour can be switched off for individual expectations
       by using the "immediately" method.

EXPECTATIONS

   will_done
          $exp->will_done( @result );

       Since version 0.04.

       Sets that method call will return a "Future" instance which will succeed with the given
       result.

   will_fail
          $exp->will_fail( $message, $category, @more );

       Since version 0.04.

       Sets that method call will return a "Future" instance which will fail with the given
       message, and optionally category name and extra details.

   immediately
          $exp->will_done( ... )->immediately;

          $exp->will_fail( ... )->immediately;

       Since version 0.02.

       Switches this expectation to return an immediate future, rather than a deferred one.

   remains_pending
          $exp->remains_pending;

       Since version 0.03.

       Sets that the future returned by this method will not complete and simply remain pending.

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

       Since version 0.04.

       Adds extra code which will run when the expected method is called, after the returned
       future has completed. This is performed by the use of "Test::Future::Deferred".

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

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>