Phpunit Util Laravel Package

Getting Started

Install the package as a dev dependency: composer require --dev amphp/phpunit-util. Requires PHP 8.1+ and PHPUnit 9+. Then extend Amp\PHPUnit\AsyncTestCase instead of the standard PHPUnit\Framework\TestCase. Your test methods can now be written as coroutines using Amp\call(), returning generators, or async functions—suspensions (e.g., socket reads, delays) are automatically handled. Start by writing a simple async test that connects to a service or uses fibers, like the example in the README: instantiate a socket, write data, and assert the response—all while using suspension-aware code.

Implementation Patterns

• Use AsyncTestCase as the base class for all async tests—its setUp() and tearDown() are fiber-aware and can suspend. Avoid the deprecated setUpAsync()/tearDownAsync() from v2.
• Return generators or use Amp\call() in test methods: Amp\call(fn() => $this->doAsyncThing()) works seamlessly, and unhandled coroutines fail the test.
• Leverage createCallback() for mocking async interactions: e.g., $mock = $this->createCallback(MyService::class, 'run'); $mock->expects($this->once())->with($this->identicalTo($arg)); returns a closure that integrates with PHPUnit’s mocking and argument assertions.
• Tighten timeouts for flaky async tests: AsyncTestCase handles timeouts natively—failures now report generator stack traces when timeouts occur (v1.2.0+).
• Integrate with AMPHP v3 ecosystem: use it alongside amphp/socket, amphp/http-client, or amphp/artax—tests run in isolated fibers with automatic loop/fiber cleanup.

Gotchas and Tips

• No manual loop control: Never call Loop::run() manually—the test runner wraps tests in fibers and manages the event loop. Manual loop invocation leads to exceptions or hangs.
• Fiber isolation matters: Each test runs in its own fiber; avoid sharing state across tests—even seemingly safe values like global or static properties may not behave as expected with suspended coroutines.
• Fiber context leaks in tearDown(): Since tearDown() now runs after the async test completes, ensure it’s also synchronous or carefully await async cleanup only if necessary—unawaited suspensions in tearDown() may cause test hangs or false passes.
• Use await instead of all(): Per v3.0.0 changes, internal usage moved from deprecated Amp\Future\all() to Amp\Future\await. Ensure your own test code mirrors this for consistency.
• Expected arguments in createCallback(): The new with() integration is powerful but subtle—e.g., createCallback(Service::class, 'process', [1, 'x']) ensures the closure is only invoked if arguments match and in that order.
• Debugging timeouts: Enable TracingDriver::dump() integration (v1.2.0+) by enabling PHPUnit’s verbose output or inspecting test output—timeout failure messages now include the generator line where it blocked.