{"id":15226359,"url":"https://github.com/seregazhuk/php-react-promise-testing","last_synced_at":"2025-04-09T20:24:14.830Z","repository":{"id":51378457,"uuid":"109965860","full_name":"seregazhuk/php-react-promise-testing","owner":"seregazhuk","description":"PHPUnit assertions for testing ReactPHP promises","archived":false,"fork":false,"pushed_at":"2023-10-06T19:06:21.000Z","size":83,"stargazers_count":32,"open_issues_count":1,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-23T22:23:59.265Z","etag":null,"topics":["async","php","phpunit","promises","reactphp"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seregazhuk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-08T11:15:39.000Z","updated_at":"2024-05-17T14:30:20.000Z","dependencies_parsed_at":"2024-06-19T00:13:08.899Z","dependency_job_id":"a6b73cc7-368d-44c4-8371-7fcc102bced6","html_url":"https://github.com/seregazhuk/php-react-promise-testing","commit_stats":{"total_commits":87,"total_committers":4,"mean_commits":21.75,"dds":"0.10344827586206895","last_synced_commit":"6614f12842525b8555f92e5a0b2f841560b03ad0"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-react-promise-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-react-promise-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-react-promise-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seregazhuk%2Fphp-react-promise-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seregazhuk","download_url":"https://codeload.github.com/seregazhuk/php-react-promise-testing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248105307,"owners_count":21048498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","php","phpunit","promises","reactphp"],"created_at":"2024-09-28T20:04:46.330Z","updated_at":"2025-04-09T20:24:14.779Z","avatar_url":"https://github.com/seregazhuk.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReactPHP Promises Testing\nA library that provides a set of convenient assertions for testing ReactPHP promises.\nUnder the hood uses [clue/php-block-react](https://github.com/clue/php-block-react) to block promises.\n\n[![Build Status](https://travis-ci.org/seregazhuk/php-react-promise-testing.svg?branch=master)](https://travis-ci.org/seregazhuk/php-react-promise-testing)\n[![Maintainability](https://api.codeclimate.com/v1/badges/689230cdae09d2e32600/maintainability)](https://codeclimate.com/github/seregazhuk/php-react-promise-testing/maintainability)\n[![Test Coverage](https://api.codeclimate.com/v1/badges/689230cdae09d2e32600/test_coverage)](https://codeclimate.com/github/seregazhuk/php-react-promise-testing/test_coverage)\n[![Total Downloads](https://poser.pugx.org/seregazhuk/react-promise-testing/downloads)](//packagist.org/packages/seregazhuk/react-promise-testing)\n\nWhen testing asynchronous code and promises things can be a bit tricky. This library provides a set of convenient \nassertions for testing ReactPHP promises. \n\n**Table of Contents**\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Assertions](#assertions)\n    - [assertPromiseFulfills()](#assertpromisefulfills)\n    - [assertPromiseFulfillsWith()](#assertpromisefulfillswith)\n    - [assertPromiseFulfillsWithInstanceOf()](#assertpromisefulfillswithinstanceof)\n    - [assertPromiseRejects()](#assertpromiserejects())\n    - [assertPromiseRejectsWith()](#assertpromiserejectswith)\n    - [assertTrueAboutPromise()](#asserttrueaboutpromise)\n    - [assertFalseAboutPromise()](#assertfalseaboutpromise)\n    \n- [Helpers](#helpers)\n    - [waitForPromiseToFulfill()](#waitforpromisetofulfill)\n    - [waitForPromise()](#waitforpromise)\n    \n## Installation\n\n### Dependencies\nLibrary requires PHP 8.0 or above.\n\nThe recommended way to install this library is via [Composer](https://getcomposer.org). \n[New to Composer?](https://getcomposer.org/doc/00-intro.md)\n\nSee also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.\n\n```\ncomposer require seregazhuk/react-promise-testing --dev\n```\n\n## Quick Start\nUse the trait `seregazhuk\\React\\PromiseTesting\\AssertsPromise` or extend your\ntest classes from `seregazhuk\\React\\PromiseTesting\\TestCase` class,\nwhich itself extends PHPUnit `TestCase`.\n\n```php\nfinal class MyTest extends TestCase\n{\n    /** @test */\n    public function promise_fulfills_with_a_response_object()\n    {\n        $browser = new Clue\\React\\Buzz\\Browser($this-\u003eeventLoop());\n        $promise = $browser-\u003eget('http://www.google.com/');\n        $this-\u003eassertPromiseFulfillsWithInstanceOf($promise, ResponseInterface::class);\n    }\n}\n```\n\nUsing the trait:\n\n```php\n\nuse PHPUnit\\Framework\\TestCase;\nuse seregazhuk\\React\\PromiseTesting\\AssertsPromise;\n\nfinal class MyTest extends TestCase\n{\n    use AssertsPromise;\n\n    /** @test */\n    public function promise_fulfills_with_a_response_object()\n    {\n        $browser = new Clue\\React\\Buzz\\Browser($this-\u003eeventLoop());\n        $promise = $browser-\u003eget('http://www.google.com/');\n        $this-\u003eassertPromiseFulfillsWithInstanceOf($promise, ResponseInterface::class);\n    }\n}\n```\n\nTest above checks that a specified promise fulfills with an instance of `ResponseInterface`. \n\n## Event loop\n\nTo make promise assertions we need to run the loop. Before each test a new instance of the event loop\nis being created (inside `setUp()` method). If you need the loop to build your dependencies you **should**\nuse `eventLoop()` method to retrieve it.\n\n\n\n## Assertions\n\n### assertPromiseFulfills()\n\n`public function assertPromiseFulfills(PromiseInterface $promise, int $timeout = null): void`\n\nThe test fails if the `$promise` rejects. \n\nYou can specify `$timeout` in seconds to wait for promise to be resolved.\nIf the promise was not fulfilled in specified timeout the test fails. When not specified, timeout is set to 2 seconds.\n\n```php\nfinal class PromiseFulfillsTest extends TestCase\n{\n    /** @test */\n    public function promise_fulfills(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003ereject();\n        $this-\u003eassertPromiseFulfills($deferred-\u003epromise(), 1);\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 189 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\PromiseFulfillTest::promise_fulfills\nFailed asserting that promise fulfills. Promise was rejected.\n```\n\n### assertPromiseFulfillsWith()\n\n`assertPromiseFulfillsWith(PromiseInterface $promise, $value, int $timeout = null): void`\n\nThe test fails if the `$promise` doesn't fulfills with a specified `$value`.\n\nYou can specify `$timeout` in seconds to wait for promise to be fulfilled.\nIf the promise was not fulfilled in specified timeout the test fails. \nWhen not specified, timeout is set to 2 seconds.\n\n```php\nfinal class PromiseFulfillsWithTest extends TestCase\n{\n    /** @test */\n    public function promise_fulfills_with_a_specified_value(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003eresolve(1234);\n        $this-\u003eassertPromiseFulfillsWith($deferred-\u003epromise(), 1);\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 180 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\PromiseFulfillsWithTest::promise_fulfills_with_a_specified_value\nFailed asserting that promise fulfills with a specified value. \nFailed asserting that 1234 matches expected 1.\n```\n\n### assertPromiseFulfillsWithInstanceOf()\n\n`assertPromiseFulfillsWithInstanceOf(PromiseInterface $promise, string $class, int $timeout = null): void`\n\nThe test fails if the `$promise` doesn't fulfills with an instance of specified `$class`.\n\nYou can specify `$timeout` in seconds to wait for promise to be fulfilled.\nIf the promise was not fulfilled in specified timeout the test fails. \nWhen not specified, timeout is set to 2 seconds.\n\n```php\nfinal class PromiseFulfillsWithInstanceOfTest extends TestCase\n{\n    /** @test */\n    public function promise_fulfills_with_an_instance_of_class(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003eresolve(new MyClass);\n        $this-\u003eassertPromiseFulfillsWithInstanceOf($deferred-\u003epromise(), MyClass::class);\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 180 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\PromiseFulfillsWithWithInstanceOfTest::promise_fulfills_with_an_instance_of_class\nFailed asserting that promise fulfills with a value of class MyClass. \n```\n\n### assertPromiseRejects()\n`assertPromiseRejects(PromiseInterface $promise, int $timeout = null): void`\n\nThe test fails if the `$promise` fulfills.\n\nYou can specify `$timeout` in seconds to wait for promise to be resolved.\nIf the promise was not fulfilled in specified timeout, it rejects with `React\\Promise\\Timer\\TimeoutException`. \nWhen not specified, timeout is set to 2 seconds.\n\n```php\nfinal class PromiseRejectsTest extends TestCase\n{\n    /** @test */\n    public function promise_rejects(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003eresolve();\n        $this-\u003eassertPromiseRejects($deferred-\u003epromise());\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 175 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\PromiseRejectsTest::promise_rejects\nFailed asserting that promise rejects. Promise was fulfilled.\n```\n\n### assertPromiseRejectsWith()\n`assertPromiseRejectsWith(PromiseInterface $promise, string $reasonExceptionClass, int $timeout = null): void`\n\nThe test fails if the `$promise` doesn't reject with a specified exception class.\n\nYou can specify `$timeout` in seconds to wait for promise to be resolved.\nIf the promise was not fulfilled in specified timeout, it rejects with `React\\Promise\\Timer\\TimeoutException`. \nWhen not specified, timeout is set to 2 seconds.\n\n```php\nfinal class PromiseRejectsWithTest extends TestCase\n{\n    /** @test */\n    public function promise_rejects_with_a_specified_reason(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003ereject(new \\LogicException());\n        $this-\u003eassertPromiseRejectsWith($deferred-\u003epromise(), \\InvalidArgumentException::class);\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 136 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\PromiseRejectsWithTest::promise_rejects_with_a_specified_reason\nFailed asserting that promise rejects with a specified reason.\nFailed asserting that LogicException Object (...) is an instance of class \"InvalidArgumentException\".\n```\n\n### assertTrueAboutPromise()\n`assertTrueAboutPromise(PromiseInterface $promise, callable $predicate, int $timeout = null): void`\n\nThe test fails if the value encapsulated in the Promise does not conform to an arbitrary predicate.\n\nYou can specify `$timeout` in seconds to wait for promise to be resolved.\nIf the promise was not fulfilled in specified timeout, it rejects with `React\\Promise\\Timer\\TimeoutException`. \nWhen not specified, timeout is set to 2 seconds.\n\n```php\nfinal class AssertTrueAboutPromiseTest extends TestCase\n{\n    /** @test */\n    public function promise_encapsulates_integer(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003eresolve(23);\n\n        $this-\u003eassertTrueAboutPromise($deferred-\u003epromise(), function ($val) {\n            return is_object($val);\n        });\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 136 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\AssertTrueAboutPromiseTest::promise_encapsulates_integer\nFailed asserting that false is true.\n```\n\n### assertFalseAboutPromise()\n`assertFalseAboutPromise(PromiseInterface $promise, callable $predicate, int $timeout = null): void`\n\nThe test fails if the value encapsulated in the Promise conforms to an arbitrary predicate.\n\nYou can specify `$timeout` in seconds to wait for promise to be resolved.\nIf the promise was not fulfilled in specified timeout, it rejects with `React\\Promise\\Timer\\TimeoutException`. \nWhen not specified, timeout is set to 2 seconds.\n\n```php\nfinal class AssertFalseAboutPromiseTest extends TestCase\n{\n    /** @test */\n    public function promise_encapsulates_object(): void\n    {\n        $deferred = new Deferred();\n        $deferred-\u003eresolve(23);\n\n        $this-\u003eassertFalseAboutPromise($deferred-\u003epromise(), function ($val) {\n            return is_int($val);\n        });\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 136 ms, Memory: 4.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\AssertFalseAboutPromiseTest::promise_encapsulates_object\nFailed asserting that true is false.\n```\n\n## Helpers\n\n### waitForPromiseToFulfill()\n`function waitForPromiseToFulfill(PromiseInterface $promise, int $timeout = null)`.\n\nThis helper can be used when you want to resolve a promise and get the resolution value.\n\nTries to resolve a `$promise` in a specified `$timeout` seconds and returns resolved value. If `$timeout` is not \nset uses 2 seconds by default. The test fails if the `$promise` doesn't fulfill.\n\n```php\nfinal class WaitForPromiseToFulfillTest extends TestCase\n{\n    /** @test */\n    public function promise_fulfills(): void\n    {\n        $deferred = new Deferred();\n\n        $deferred-\u003ereject(new \\Exception());\n        $value = $this-\u003ewaitForPromiseToFulfill($deferred-\u003epromise());\n    }\n}\n```\n\n```bash\nPHPUnit 8.5.2 by Sebastian Bergmann and contributors.\n\nF                                                                   1 / 1 (100%)\n\nTime: 223 ms, Memory: 6.00MB\n\nThere was 1 failure:\n\n1) seregazhuk\\React\\PromiseTesting\\tests\\WaitForPromiseToFulfillTest::promise_fulfills\nFailed to fulfill a promise. It was rejected with Exception.\n```\n\n### waitForPromise()\n`function waitForPromise(PromiseInterface $promise, int $timeout = null)`.\n\nTries to resolve a specified `$promise` in a specified `$timeout` seconds. If `$timeout` is not set uses 2 \nseconds by default. If the promise fulfills returns a resolution value, otherwise throws an exception. If the \npromise rejects throws the rejection reason, if the promise doesn't fulfill in a specified `$timeout` throws \n`React\\Promise\\Timer\\TimeoutException`.\n\nThis helper can be useful when you need to get the value from the fulfilled promise in a synchronous way:\n\n```php\n$value = $this-\u003ewaitForPromise($cache-\u003eget('key'));\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseregazhuk%2Fphp-react-promise-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseregazhuk%2Fphp-react-promise-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseregazhuk%2Fphp-react-promise-testing/lists"}