Weave Code
Testing Laravel Package
hyperf/testing
Official testing utilities for the Hyperf framework: PHPUnit integration, coroutine-aware helpers, HTTP assertions, and database testing support, making it easy to write fast, reliable tests for Swoole-based PHP applications.
At a glance
Frequently asked questions about Testing
- What is hyperf/testing used for?
- hyperf/testing is the official testing toolkit for Hyperf applications. It adds PHPUnit integration, coroutine-aware test lifecycle handling, fluent HTTP assertions, database testing traits, and container or mocking helpers. It is designed for feature and integration tests in Swoole-based PHP services.
- How do I install hyperf/testing in a Hyperf project?
- Install it as a dev dependency with composer require --dev hyperf/testing. Then configure PHPUnit to use the Hyperf test bootstrap and run tests through the Hyperf PHPUnit binary so the container and coroutine runtime are initialized correctly. Keep the package out of production dependencies.
- Does hyperf/testing work with PHPUnit and which versions are supported?
- hyperf/testing is built around PHPUnit and adds Hyperf-specific bootstrapping and coroutine-aware helpers. The PHPUnit version you can use depends on the hyperf/testing release and your Hyperf framework version, so check the package's composer.json constraints before upgrading. In most projects you should let Composer resolve compatible PHPUnit and hyperf/testing versions together.
- How do I write HTTP feature tests with fluent assertions in Hyperf?
- Use the fluent HTTP helpers on your test case to issue requests, for example get, post, put, and delete, then chain assertions such as assertStatus, assertJson, and assertSee. The helpers route requests through the Hyperf application container, so middleware, routing, and validation behave like a real request. This makes them suitable for feature tests of controllers and APIs.
- How does database testing and RefreshDatabase work in hyperf/testing?
- hyperf/testing provides database testing traits that can wrap each test in a transaction and roll it back, similar to Laravel's RefreshDatabase workflow. You can also use refresh traits to rebuild schema or seed data when a transactional rollback is not enough. Because Hyperf runs in coroutines, make sure database connections are not shared across tests in unsafe ways.
- Why do my Hyperf tests fail with coroutine or Swoole errors?
- Most coroutine failures come from running tests outside the Hyperf test runner or from sharing Swoole resources between tests. Run the Hyperf PHPUnit binary, keep per-test state isolated, and avoid blocking calls inside coroutines. If you see container or connection errors, check that the test bootstrap initializes the Hyperf application correctly.
- Can I mock services and use the dependency injection container in Hyperf tests?
- Yes. You can bind fake implementations into the Hyperf container, use Mockery or PHPUnit mocks, and resolve services through the container in your tests. The dependency-injection utilities let you swap real services for test doubles while preserving the application's normal wiring. Clear mocks between tests to avoid coroutine cross-contamination.
- Is hyperf/testing suitable for CI pipelines and production testing?
- hyperf/testing is a development dependency and is not needed in production runtime. It is well suited to CI pipelines as long as the CI image includes PHP, Swoole, and any database services your tests need. Cache Composer dependencies and run tests through the same Hyperf PHPUnit command you use locally.
- What are alternatives to hyperf/testing for testing Hyperf applications?
- The main alternative is plain PHPUnit with manual Hyperf bootstrap code, which gives you control but loses the fluent helpers. Mockery is commonly used alongside hyperf/testing for mocks, and Laravel's testing utilities are only a good fit if you are actually testing a Laravel application. For Hyperf projects, hyperf/testing is the official, framework-aligned option.
- How is hyperf/testing maintained and which Hyperf versions are supported?
- hyperf/testing is maintained as part of the official Hyperf organization and its releases track Hyperf framework versions. Check the package's release notes and composer.json constraints to confirm support for your Hyperf and PHPUnit versions. Pin compatible versions in composer.json and upgrade testing utilities together with the framework.
Weaver
How can I help you explore Laravel packages today?