- How do I install wyrihaximus/async-test-utilities in a Laravel project?
- Install it with Composer, typically as a dev dependency: composer require --dev wyrihaximus/async-test-utilities. Because it is a test utility package, it should not be part of your production runtime dependencies. After installation, make your async test classes extend WyriHaximus\AsyncTestUtilities\AsyncTestCase or a custom Laravel bridge class. Check your PHP, PHPUnit, and ReactPHP constraints before committing the lockfile.
- Does AsyncTestCase work with Laravel's default PHPUnit TestCase?
- No. WyriHaximus\AsyncTestUtilities\AsyncTestCase does not inherit from Laravel's TestCase, so Laravel helpers and traits such as RefreshDatabase are not available automatically. You need a custom base class that extends AsyncTestCase and bootstraps the Laravel application, for example by implementing createApplication or equivalent setup. This bridge should also handle Laravel container binding and teardown carefully when tests run inside fibers.
- How does fiber-based async test execution work in this package?
- Every test method runs inside a fiber, allowing you to use ReactPHP async and await patterns without blocking the whole test process. The package enforces a default timeout of 30 seconds so hung promises or unresolved I/O do not stall the suite. You can tune that timeout per test class or method with the TimeOut attribute. Fiber-based tests are best suited to non-blocking I/O scenarios such as HTTP clients, queues, and async jobs.
- How do I set a custom timeout for a slow async test?
- Use the TimeOut attribute from WyriHaximus\AsyncTestUtilities, for example #[TimeOut(1)] for one second or #[TimeOut(0.3)] for 300 milliseconds. It can be applied at class level and method level; when both are present, the method-level value takes priority. Raise the timeout for slow external API calls and lower it for fast tests that should fail quickly. The default remains 30 seconds when no attribute is set.
- Is this package compatible with Laravel 10, Laravel 11, or newer?
- The package does not advertise Laravel-specific version support; compatibility depends on your PHP version, PHPUnit version, and ReactPHP dependencies. It can align with Laravel 11+ async experiments involving Swoole or ReactPHP, but you still need a custom bridge to Laravel's TestCase. Laravel 10 or older projects are more likely to hit PHPUnit and dependency conflicts because the 14.5.0 release requires PHPUnit ^13.4.1. Verify the full Composer dependency graph before adopting it.
- What are the random namespaces and directories for in async tests?
- AsyncTestCase provides random namespaces and random directories so file-based tests can write to isolated locations without hard-coded paths. This reduces collisions when tests run repeatedly or in parallel and is useful for storage adapters, cache files, and other filesystem-related async tests. You can use the generated paths in your test setup instead of managing temporary folders manually. The feature is focused on test isolation, not on Laravel's storage facades specifically.
- Can I use these async test utilities for Laravel database, queue, and HTTP client tests?
- They are strongest for non-blocking I/O tests such as ReactPHP-backed HTTP clients, queue workers, and async jobs. Laravel's Eloquent and query builder are synchronous, so async database tests need custom adapters, mocking, or a separate strategy. File storage and API client tests benefit most from the random directories and fiber timeouts. Database-heavy suites may get less value unless you deliberately redesign those tests around async execution.
- What PHPUnit version does wyrihaximus/async-test-utilities require, and will it conflict with Laravel?
- The 14.5.0 release notes list PHPUnit ^13.4.1, a major jump from the previous ^12.5 requirement. Laravel projects often pin older PHPUnit versions, so this can conflict with existing test tooling, CI images, and third-party test packages. It also depends on ReactPHP components such as react/event-loop, which may overlap with Laravel's async stack or HTTP client dependencies. Use Composer constraints, aliases, or overrides only after testing the full dependency graph.
- What breaking changes should I review before upgrading from 12.x to 14.x?
- The jump from 12.2.0 to 14.5.0 is large, even though the 14.5.0 notes mainly show automated dependency and CI updates. You should review the intermediate 13.x and 14.0 through 14.4 release notes for API or behavioral changes. Pay special attention to the PHPUnit ^13.4.1 requirement and any changes to AsyncTestCase, TimeOut handling, or fiber execution. Re-run your Laravel bridge tests and check for fiber leaks or timeout regressions before upgrading.
- What alternatives exist for async testing in Laravel, and is this package actively maintained?
- Alternatives include Laravel's built-in synchronous test helpers, PHPUnit with custom ReactPHP wrappers, Amp's PHPUnit integration, and bespoke fiber-based test base classes. This package is a focused ReactPHP-oriented utility rather than a full Laravel testing framework, so evaluate it against your async stack. Check recent Packagist releases and GitHub activity, and monitor ReactPHP and PHPUnit updates because dependency churn is the main maintenance risk. If you only need occasional async tests, a smaller custom bridge may be easier to maintain.