Download the PHP package seregazhuk/react-promise-testing without Composer

ReactPHP Promises Testing

A library that provides a set of convenient assertions for testing ReactPHP promises. Under the hood uses clue/php-block-react to block promises.

When testing asynchronous code and promises things can be a bit tricky. This library provides a set of convenient assertions for testing ReactPHP promises.

Table of Contents

• Installation
• Quick Start

• Assertions

  • assertPromiseFulfills()
  • assertPromiseFulfillsWith()
  • assertPromiseFulfillsWithInstanceOf()
  • [assertPromiseRejects()](#assertpromiserejects())
  • assertPromiseRejectsWith()
  • assertTrueAboutPromise()
  • assertFalseAboutPromise()
• Helpers
  • waitForPromiseToFulfill()
  • waitForPromise()

Installation

Dependencies

Library requires PHP 8.0 or above.

The recommended way to install this library is via Composer. New to Composer?

See also the CHANGELOG for details about version upgrades.

Quick Start

Use the trait seregazhuk\React\PromiseTesting\AssertsPromise or extend your test classes from seregazhuk\React\PromiseTesting\TestCase class, which itself extends PHPUnit TestCase.

Using the trait:

Test above checks that a specified promise fulfills with an instance of ResponseInterface.

Event loop

To make promise assertions we need to run the loop. Before each test a new instance of the event loop is being created (inside setUp() method). If you need the loop to build your dependencies you should use eventLoop() method to retrieve it.

Assertions

assertPromiseFulfills()

public function assertPromiseFulfills(PromiseInterface $promise, int $timeout = null): void

The test fails if the $promise rejects.

You can specify $timeout in seconds to wait for promise to be resolved. If the promise was not fulfilled in specified timeout the test fails. When not specified, timeout is set to 2 seconds.

assertPromiseFulfillsWith()

assertPromiseFulfillsWith(PromiseInterface $promise, $value, int $timeout = null): void

The test fails if the $promise doesn't fulfills with a specified $value.

You can specify $timeout in seconds to wait for promise to be fulfilled. If the promise was not fulfilled in specified timeout the test fails. When not specified, timeout is set to 2 seconds.

assertPromiseFulfillsWithInstanceOf()

assertPromiseFulfillsWithInstanceOf(PromiseInterface $promise, string $class, int $timeout = null): void

The test fails if the $promise doesn't fulfills with an instance of specified $class.

You can specify $timeout in seconds to wait for promise to be fulfilled. If the promise was not fulfilled in specified timeout the test fails. When not specified, timeout is set to 2 seconds.

assertPromiseRejects()

assertPromiseRejects(PromiseInterface $promise, int $timeout = null): void

The test fails if the $promise fulfills.

You can specify $timeout in seconds to wait for promise to be resolved. If the promise was not fulfilled in specified timeout, it rejects with React\Promise\Timer\TimeoutException. When not specified, timeout is set to 2 seconds.

assertPromiseRejectsWith()

assertPromiseRejectsWith(PromiseInterface $promise, string $reasonExceptionClass, int $timeout = null): void

The test fails if the $promise doesn't reject with a specified exception class.

You can specify $timeout in seconds to wait for promise to be resolved. If the promise was not fulfilled in specified timeout, it rejects with React\Promise\Timer\TimeoutException. When not specified, timeout is set to 2 seconds.

assertTrueAboutPromise()

assertTrueAboutPromise(PromiseInterface $promise, callable $predicate, int $timeout = null): void

The test fails if the value encapsulated in the Promise does not conform to an arbitrary predicate.

You can specify $timeout in seconds to wait for promise to be resolved. If the promise was not fulfilled in specified timeout, it rejects with React\Promise\Timer\TimeoutException. When not specified, timeout is set to 2 seconds.

assertFalseAboutPromise()

assertFalseAboutPromise(PromiseInterface $promise, callable $predicate, int $timeout = null): void

The test fails if the value encapsulated in the Promise conforms to an arbitrary predicate.

You can specify $timeout in seconds to wait for promise to be resolved. If the promise was not fulfilled in specified timeout, it rejects with React\Promise\Timer\TimeoutException. When not specified, timeout is set to 2 seconds.

Helpers

waitForPromiseToFulfill()

function waitForPromiseToFulfill(PromiseInterface $promise, int $timeout = null).

This helper can be used when you want to resolve a promise and get the resolution value.

Tries to resolve a $promise in a specified $timeout seconds and returns resolved value. If $timeout is not set uses 2 seconds by default. The test fails if the $promise doesn't fulfill.

waitForPromise()

function waitForPromise(PromiseInterface $promise, int $timeout = null).

Tries to resolve a specified $promise in a specified $timeout seconds. If $timeout is not set uses 2 seconds by default. If the promise fulfills returns a resolution value, otherwise throws an exception. If the promise rejects throws the rejection reason, if the promise doesn't fulfill in a specified $timeout throws React\Promise\Timer\TimeoutException.

This helper can be useful when you need to get the value from the fulfilled promise in a synchronous way: