React Phpunit Run Tests In Fiber Laravel Package

Getting Started

Install the package in your Laravel project’s dev dependencies:

composer require --dev wyrihaximus/react-phpunit-run-tests-in-fiber

Prerequisites: PHP 8.4+, PHPUnit 12.3+, and react/async (already required implicitly via wyrihaximus/react-phpunit-run-tests-in-fiber).
Start by adding the trait to one test class that needs to test await()-based async logic:

use PHPUnit\Framework\TestCase;
use WyriHaximus\React\PHPUnit\RunTestsInFibersTrait;

final class AsyncServiceTest extends TestCase
{
    use RunTestsInFibersTrait;

    #[test]
    public function itRunsAwaitInFiber(): void
    {
        // Your await() calls now work here
        $result = \React\Async\await(someAsyncPromise());
        $this->assertTrue($result);
    }
}

💡 First use case: Testing ReactPHP-based services (e.g., non-blocking HTTP clients, event loops) that require await() but would otherwise fail with "Cannot await outside fiber" errors.

Implementation Patterns

• Selective Trait Usage: Only apply the trait to tests needing fibers. Standard Laravel tests (e.g., HTTP assertions, database interactions) remain sync and fast.
• Async Integration Testing: Write realistic end-to-end tests for async layers (e.g., WebSocket handlers, event processors) using react/http-client or react/socket without manual loop setup.
• Timeout Enforcement: Apply class-level defaults and method-level overrides for reliability:

  #[\WyriHaximus\React\PHPUnit\TimeOut(10)] // Default 10s timeout
  final class AsyncServiceTest extends TestCase
  {
      use RunTestsInFibersTrait;
  
      #[\WyriHaximus\React\PHPUnit\TimeOut(1)] // Override for slow ops
      public function itTimesOutOnSlowOperation(): void { ... }
  }
  

• Testing Event Loop Tasks: Use timers, streams, or custom loop tasks inside tests (e.g., loop->addTimer()), since the trait manages the loop lifecycle around each test.
• Avoiding Global State Conflicts: Never share loops/fixtures across test classes when using this trait — each test runs with its own isolated loop context.

Gotchas and Tips

• No Fiber Killing: Timeouts fail the test but leave background fibers running. Always wrap long-running async ops in timeout/cancellation (e.g., Promise\timeout() from react/promise).
• PHP/PHPUnit Version Lock: Downgrading to PHP <8.4 or PHPUnit <12.3 silently breaks tests. Pin versions in composer.json:

  {
      "require-dev": {
          "php": "^8.4",
          "phpunit/phpunit": "^12.3"
      }
  }
  

• Laravel Compatibility: Avoid using this with Laravel’s built-in async features (e.g., queue workers, Bus::dispatchSync()) — Laravel’s sync architecture conflicts with ReactPHP’s event loop. Best for isolated async modules, not full-stack Laravel tests.
• Debugging: When tests hang, check for:
  • Missing await() on promises
  • Unhandled promise rejections
  • Timers/futures never resolving due to logic bugs
• Coverage Gaps: Due to fiber indirection, Xdebug coverage may report incomplete lines. Use // @codeCoverageIgnore on await() lines if needed.