Utopia Tests

A lightweight PHP testing library that provides useful testing utilities and extensions for PHPUnit.

Installation

composer require utopia-php/tests

Requirements

• PHP 8.3 or later
• PHPUnit 12.4 or later

Features

Async Extension

The Async trait provides utilities for testing asynchronous or eventually consistent behavior.

assertEventually()

Repeatedly executes a callable until it succeeds or times out. This is useful for testing:

• Asynchronous operations
• Eventually consistent systems
• Polling-based workflows
• Background jobs

Usage:

use PHPUnit\Framework\TestCase;
use Utopia\Tests\Extensions\Async;

class MyTest extends TestCase
{
    use Async;

    public function testAsyncOperation(): void
    {
        $result = null;

        // Start some async operation
        $this->startAsyncJob(function ($data) use (&$result) {
            $result = $data;
        });

        // Wait until the result is set (max 10 seconds, check every 500ms)
        self::assertEventually(function () use (&$result) {
            $this->assertNotNull($result);
            $this->assertSame('expected', $result);
        }, timeoutMs: 10000, waitMs: 500);
    }
}

Parameters:

• callable $probe - The function to execute repeatedly. Should contain assertions.
• int $timeoutMs - Maximum time to wait in milliseconds (default: 10000)
• int $waitMs - Time to wait between attempts in milliseconds (default: 500)

Critical Exceptions:

If you need to immediately fail the test without retrying, throw a Critical exception:

use Utopia\Tests\Extensions\Async\Exceptions\Critical;

self::assertEventually(function () use ($connection) {
    if ($connection->isClosed()) {
        throw new Critical('Connection closed unexpectedly');
    }
    $this->assertTrue($connection->hasData());
});

Development

Run Tests

composer install --ignore-platform-reqs
composer test

Code Formatting

composer format

Static Analysis

composer check

Linting

composer lint

License

MIT License. See LICENSE for more information.