|
| 1 | +# Co-PHPUnit |
| 2 | + |
| 3 | +[](https://packagist.org/packages/friendsofhyperf/co-phpunit) |
| 4 | +[](https://packagist.org/packages/friendsofhyperf/co-phpunit) |
| 5 | +[](https://github.com/friendsofhyperf/components) |
| 6 | + |
| 7 | +A PHPUnit extension that enables tests to run inside Swoole coroutines, specifically designed for testing Hyperf applications and other Swoole-based frameworks. |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +```bash |
| 12 | +composer require friendsofhyperf/co-phpunit --dev |
| 13 | +``` |
| 14 | + |
| 15 | +## Why Co-PHPUnit? |
| 16 | + |
| 17 | +When testing Hyperf applications, many components rely on Swoole's coroutine context to function properly. Running tests in a traditional synchronous environment can lead to issues such as: |
| 18 | + |
| 19 | +- Coroutine context not being available |
| 20 | +- Timers and event loops not working correctly |
| 21 | +- Coordinator pattern failures |
| 22 | +- Database connection pool issues |
| 23 | + |
| 24 | +Co-PHPUnit solves these problems by automatically wrapping test execution in a Swoole coroutine context when needed. |
| 25 | + |
| 26 | +## Usage |
| 27 | + |
| 28 | +### Basic Usage |
| 29 | + |
| 30 | +Simply use the `RunTestsInCoroutine` trait in your test class: |
| 31 | + |
| 32 | +```php |
| 33 | +<?php |
| 34 | + |
| 35 | +namespace Your\Namespace\Tests; |
| 36 | + |
| 37 | +use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine; |
| 38 | +use PHPUnit\Framework\TestCase; |
| 39 | + |
| 40 | +class YourTest extends TestCase |
| 41 | +{ |
| 42 | + use RunTestsInCoroutine; |
| 43 | + |
| 44 | + public function testSomething() |
| 45 | + { |
| 46 | + // Your test code here |
| 47 | + // This will automatically run inside a Swoole coroutine |
| 48 | + } |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +### Disabling Coroutine for Specific Tests |
| 53 | + |
| 54 | +If you need to disable coroutine execution for a specific test class, set the `$enableCoroutine` property to `false`: |
| 55 | + |
| 56 | +```php |
| 57 | +<?php |
| 58 | + |
| 59 | +namespace Your\Namespace\Tests; |
| 60 | + |
| 61 | +use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine; |
| 62 | +use PHPUnit\Framework\TestCase; |
| 63 | + |
| 64 | +class YourTest extends TestCase |
| 65 | +{ |
| 66 | + use RunTestsInCoroutine; |
| 67 | + |
| 68 | + protected bool $enableCoroutine = false; |
| 69 | + |
| 70 | + public function testSomething() |
| 71 | + { |
| 72 | + // This test will run in normal synchronous mode |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +## How It Works |
| 78 | + |
| 79 | +The `RunTestsInCoroutine` trait overrides PHPUnit's `runBare()` method to: |
| 80 | + |
| 81 | +1. **Check Prerequisites**: Verifies that the Swoole extension is loaded and not already in a coroutine context |
| 82 | +2. **Create Coroutine Context**: Wraps test execution in `Swoole\Coroutine\run()` |
| 83 | +3. **Exception Handling**: Properly captures and re-throws exceptions from within the coroutine |
| 84 | +4. **Cleanup**: Clears all timers and resumes coordinator on test completion |
| 85 | +5. **Fallback**: If conditions aren't met, falls back to normal test execution |
| 86 | + |
| 87 | +### PHPUnit Patch |
| 88 | + |
| 89 | +The package includes a `phpunit-patch.php` file that automatically removes the `final` keyword from PHPUnit's `TestCase::runBare()` method, allowing the trait to override it. This patch is applied automatically when the package is autoloaded. |
| 90 | + |
| 91 | +## Requirements |
| 92 | + |
| 93 | +- PHP >= 8.0 |
| 94 | +- PHPUnit >= 10.0 |
| 95 | +- Swoole extension (when running tests in coroutine mode) |
| 96 | +- Hyperf >= 3.1 (for coordinator functionality) |
| 97 | + |
| 98 | +## Configuration |
| 99 | + |
| 100 | +### Composer Autoload |
| 101 | + |
| 102 | +The package automatically registers its autoload files in composer.json: |
| 103 | + |
| 104 | +```json |
| 105 | +{ |
| 106 | + "autoload-dev": { |
| 107 | + "psr-4": { |
| 108 | + "Your\\Tests\\": "tests/" |
| 109 | + }, |
| 110 | + "files": [ |
| 111 | + "vendor/friendsofhyperf/co-phpunit/phpunit-patch.php" |
| 112 | + ] |
| 113 | + } |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +### PHPUnit Configuration |
| 118 | + |
| 119 | +No special PHPUnit configuration is required. The package works seamlessly with your existing `phpunit.xml` configuration. |
| 120 | + |
| 121 | +## Best Practices |
| 122 | + |
| 123 | +1. **Use for Integration Tests**: This is particularly useful for integration tests that interact with Hyperf's coroutine-aware components |
| 124 | +2. **Selective Enablement**: Not all tests need to run in coroutines. Use `$enableCoroutine = false` for unit tests that don't require coroutine context |
| 125 | +3. **Test Isolation**: The package automatically cleans up timers and coordinator state between tests |
| 126 | +4. **Performance**: Tests running in coroutines may have slightly different performance characteristics |
| 127 | + |
| 128 | +## Example: Testing Hyperf Services |
| 129 | + |
| 130 | +```php |
| 131 | +<?php |
| 132 | + |
| 133 | +namespace App\Tests; |
| 134 | + |
| 135 | +use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine; |
| 136 | +use Hyperf\Context\ApplicationContext; |
| 137 | +use PHPUnit\Framework\TestCase; |
| 138 | + |
| 139 | +class ServiceTest extends TestCase |
| 140 | +{ |
| 141 | + use RunTestsInCoroutine; |
| 142 | + |
| 143 | + public function testServiceWithCoroutineContext() |
| 144 | + { |
| 145 | + // Get service from container |
| 146 | + $service = ApplicationContext::getContainer()->get(YourService::class); |
| 147 | + |
| 148 | + // Test methods that use coroutine context |
| 149 | + $result = $service->asyncOperation(); |
| 150 | + |
| 151 | + $this->assertNotNull($result); |
| 152 | + } |
| 153 | + |
| 154 | + public function testDatabaseConnection() |
| 155 | + { |
| 156 | + // Test database operations that require connection pool |
| 157 | + $result = Db::table('users')->first(); |
| 158 | + |
| 159 | + $this->assertIsArray($result); |
| 160 | + } |
| 161 | +} |
| 162 | +``` |
| 163 | + |
| 164 | +## Troubleshooting |
| 165 | + |
| 166 | +### Tests Hang or Timeout |
| 167 | + |
| 168 | +If tests hang, ensure that: |
| 169 | +- All async operations are properly awaited |
| 170 | +- No infinite loops exist in coroutine callbacks |
| 171 | +- Timers are cleared in test teardown |
| 172 | + |
| 173 | +### "Call to a member function on null" |
| 174 | + |
| 175 | +This usually indicates that coroutine context is not available. Ensure: |
| 176 | +- Swoole extension is installed and enabled |
| 177 | +- The `RunTestsInCoroutine` trait is included |
| 178 | +- `$enableCoroutine` is set to `true` |
| 179 | + |
| 180 | +### PHPUnit Version Compatibility |
| 181 | + |
| 182 | +The package supports PHPUnit 10.x, 11.x, and 12.x. Ensure your PHPUnit version is compatible. |
| 183 | + |
| 184 | +## Contributing |
| 185 | + |
| 186 | +Contributions are welcome! Please feel free to submit a Pull Request. |
| 187 | + |
| 188 | +## Support |
| 189 | + |
| 190 | +- Issues: [GitHub Issues](https://github.com/friendsofhyperf/components/issues) |
| 191 | +- Documentation: [Hyperf Fans](https://hyperf.fans) |
| 192 | +- Pull Requests: [GitHub Pull Requests](https://github.com/friendsofhyperf/components/pulls) |
| 193 | + |
| 194 | +## License |
| 195 | + |
| 196 | +This package is open-sourced software licensed under the [MIT license](LICENSE). |
| 197 | + |
| 198 | +## Credits |
| 199 | + |
| 200 | +- [huangdijia](https://github.com/huangdijia) |
| 201 | +- [All Contributors](https://github.com/friendsofhyperf/components/graphs/contributors) |
0 commit comments