---
name: "Test::ExpectAndCheck::Future"
section: "3pm"
platform: "linux"
package: "libtest-expectandcheck-perl"
version: "0.07-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::ExpectAndCheck::Future"
---

# Test::ExpectAndCheck::Future(3pm)

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

## 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\>