README

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()
  • 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.

composer require seregazhuk/react-promise-testing --dev

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.

final class MyTest extends TestCase
{
    /** @test */
    public function promise_fulfills_with_a_response_object()
    {
        $browser = new Clue\React\Buzz\Browser($this->eventLoop());
        $promise = $browser->get('http://www.google.com/');
        $this->assertPromiseFulfillsWithInstanceOf($promise, ResponseInterface::class);
    }
}

Using the trait:

use PHPUnit\Framework\TestCase;
use seregazhuk\React\PromiseTesting\AssertsPromise;

final class MyTest extends TestCase
{
    use AssertsPromise;

    /** @test */
    public function promise_fulfills_with_a_response_object()
    {
        $browser = new Clue\React\Buzz\Browser($this->eventLoop());
        $promise = $browser->get('http://www.google.com/');
        $this->assertPromiseFulfillsWithInstanceOf($promise, ResponseInterface::class);
    }
}

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.

final class PromiseFulfillsTest extends TestCase
{
    /** @test */
    public function promise_fulfills(): void
    {
        $deferred = new Deferred();
        $deferred->reject();
        $this->assertPromiseFulfills($deferred->promise(), 1);
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 189 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\PromiseFulfillTest::promise_fulfills
Failed asserting that promise fulfills. Promise was rejected.

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.

final class PromiseFulfillsWithTest extends TestCase
{
    /** @test */
    public function promise_fulfills_with_a_specified_value(): void
    {
        $deferred = new Deferred();
        $deferred->resolve(1234);
        $this->assertPromiseFulfillsWith($deferred->promise(), 1);
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 180 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\PromiseFulfillsWithTest::promise_fulfills_with_a_specified_value
Failed asserting that promise fulfills with a specified value. 
Failed asserting that 1234 matches expected 1.

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.

final class PromiseFulfillsWithInstanceOfTest extends TestCase
{
    /** @test */
    public function promise_fulfills_with_an_instance_of_class(): void
    {
        $deferred = new Deferred();
        $deferred->resolve(new MyClass);
        $this->assertPromiseFulfillsWithInstanceOf($deferred->promise(), MyClass::class);
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 180 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\PromiseFulfillsWithWithInstanceOfTest::promise_fulfills_with_an_instance_of_class
Failed asserting that promise fulfills with a value of class MyClass. 

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.

final class PromiseRejectsTest extends TestCase
{
    /** @test */
    public function promise_rejects(): void
    {
        $deferred = new Deferred();
        $deferred->resolve();
        $this->assertPromiseRejects($deferred->promise());
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 175 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\PromiseRejectsTest::promise_rejects
Failed asserting that promise rejects. Promise was fulfilled.

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.

final class PromiseRejectsWithTest extends TestCase
{
    /** @test */
    public function promise_rejects_with_a_specified_reason(): void
    {
        $deferred = new Deferred();
        $deferred->reject(new \LogicException());
        $this->assertPromiseRejectsWith($deferred->promise(), \InvalidArgumentException::class);
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 136 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\PromiseRejectsWithTest::promise_rejects_with_a_specified_reason
Failed asserting that promise rejects with a specified reason.
Failed asserting that LogicException Object (...) is an instance of class "InvalidArgumentException".

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.

final class AssertTrueAboutPromiseTest extends TestCase
{
    /** @test */
    public function promise_encapsulates_integer(): void
    {
        $deferred = new Deferred();
        $deferred->resolve(23);

        $this->assertTrueAboutPromise($deferred->promise(), function ($val) {
            return is_object($val);
        });
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 136 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\AssertTrueAboutPromiseTest::promise_encapsulates_integer
Failed asserting that false is true.

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.

final class AssertFalseAboutPromiseTest extends TestCase
{
    /** @test */
    public function promise_encapsulates_object(): void
    {
        $deferred = new Deferred();
        $deferred->resolve(23);

        $this->assertFalseAboutPromise($deferred->promise(), function ($val) {
            return is_int($val);
        });
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 136 ms, Memory: 4.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\AssertFalseAboutPromiseTest::promise_encapsulates_object
Failed asserting that true is false.

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.

final class WaitForPromiseToFulfillTest extends TestCase
{
    /** @test */
    public function promise_fulfills(): void
    {
        $deferred = new Deferred();

        $deferred->reject(new \Exception());
        $value = $this->waitForPromiseToFulfill($deferred->promise());
    }
}

PHPUnit 8.5.2 by Sebastian Bergmann and contributors.

F                                                                   1 / 1 (100%)

Time: 223 ms, Memory: 6.00MB

There was 1 failure:

1) seregazhuk\React\PromiseTesting\tests\WaitForPromiseToFulfillTest::promise_fulfills
Failed to fulfill a promise. It was rejected with Exception.

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:

$value = $this->waitForPromise($cache->get('key'));