NAME

       "Test::Future::AsyncAwait::Awaitable" - conformance tests for awaitable role API

SYNOPSIS

          use Test::More;
          use Test::Future::AsyncAwait::Awaitable;

          use My::Future::Subclass;

          test_awaitable "My subclass of Future",
             class => "My::Future::Subclass";

          done_testing;

DESCRIPTION

       This module provides a single test function, which runs a suite of subtests to check that a given class
       provides a useable implementation of the Future::AsyncAwait::Awaitable role. It runs tests that simulate
       various ways in which Future::AsyncAwait will try to use an instance of this class, to check that the
       implementation is valid.

FUNCTIONS

   test_awaitable
          test_awaitable( $title, %args )

       Runs the API conformance tests. $title is printed in the test description output so should be some human-
       friendly string.

       Takes the following named arguments:

       class => STRING
           Gives  the  name  of  the class. This is the class on which the "AWAIT_NEW_DONE" and "AWAIT_NEW_FAIL"
           methods will be invoked.

       new => CODE
           Optional. Gives a callback function to invoke to construct a new pending instance; used by the  tests
           to create pending instances that would be passed into the "await" keyword. As this is not part of the
           API as such, the test code does not rely on being able to directly perform it via the API.

           This  argument  is  optional;  if  not provided the tests will simply try to invoke the regular "new"
           constructor on the given class name. For most implementations this should be sufficient.

              $f = $new->()

       cancel => CODE
           Optional. Gives a callback function to invoke to cancel a pending  instance,  if  the  implementation
           provides  cancellation  semantics. If this callback is provided then an extra subtest suite is run to
           check the API around cancellation.

              $cancel->( $f )

       force => CODE
           Optional. Gives a callback function to invoke to wait for a promise to invoke its on-ready callbacks.
           Some future-like implementations will run these immediately when the future  is  marked  as  done  or
           failed,  and  so  this  callback  will  not  be  required.  Other  implementations  will  defer these
           invocations, perhaps until the next tick of an event loop or  similar.  In  the  latter  case,  these
           implementations should provide a way for the test to wait for this to happen.

              $force->( $f )

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>

perl v5.38.2                                       2024-04-01              Test::Future::...wait::Awaitable(3pm)