|
| 1 | +# Co-PHPUnit |
| 2 | + |
| 3 | +A PHPUnit extension that enables tests to run within Swoole coroutines, specifically designed for testing Hyperf applications and other Swoole-based frameworks. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +```bash |
| 8 | +composer require friendsofhyperf/co-phpunit --dev |
| 9 | +``` |
| 10 | + |
| 11 | +## Why Co-PHPUnit? |
| 12 | + |
| 13 | +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: |
| 14 | + |
| 15 | +- Coroutine context being unavailable |
| 16 | +- Timers and event loops not working correctly |
| 17 | +- Coordinator pattern failures |
| 18 | +- Database connection pool problems |
| 19 | + |
| 20 | +Co-PHPUnit addresses these issues by automatically wrapping test execution within Swoole coroutine contexts when needed. |
| 21 | + |
| 22 | +## Usage |
| 23 | + |
| 24 | +### Basic Usage |
| 25 | + |
| 26 | +Simply use the `RunTestsInCoroutine` trait in your test class: |
| 27 | + |
| 28 | +```php |
| 29 | +<?php |
| 30 | + |
| 31 | +namespace Your\Namespace\Tests; |
| 32 | + |
| 33 | +use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine; |
| 34 | +use PHPUnit\Framework\TestCase; |
| 35 | + |
| 36 | +class YourTest extends TestCase |
| 37 | +{ |
| 38 | + use RunTestsInCoroutine; |
| 39 | + |
| 40 | + public function testSomething() |
| 41 | + { |
| 42 | + // Your test code |
| 43 | + // This will automatically run within a Swoole coroutine |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +### Disabling Coroutine for Specific Tests |
| 49 | + |
| 50 | +If you need to disable coroutine execution for a particular test class, set the `$enableCoroutine` property to `false`: |
| 51 | + |
| 52 | +```php |
| 53 | +<?php |
| 54 | + |
| 55 | +namespace Your\Namespace\Tests; |
| 56 | + |
| 57 | +use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine; |
| 58 | +use PHPUnit\Framework\TestCase; |
| 59 | + |
| 60 | +class YourTest extends TestCase |
| 61 | +{ |
| 62 | + use RunTestsInCoroutine; |
| 63 | + |
| 64 | + protected bool $enableCoroutine = false; |
| 65 | + |
| 66 | + public function testSomething() |
| 67 | + { |
| 68 | + // This test will run in normal synchronous mode |
| 69 | + } |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +## How It Works |
| 74 | + |
| 75 | +The `RunTestsInCoroutine` trait overrides PHPUnit's `runBare()` method to: |
| 76 | + |
| 77 | +1. **Check Prerequisites**: Verify that the Swoole extension is loaded and not already in a coroutine context |
| 78 | +2. **Create Coroutine Context**: Wrap test execution within `Swoole\Coroutine\run()` |
| 79 | +3. **Exception Handling**: Properly catch and re-throw exceptions from within coroutines |
| 80 | +4. **Cleanup**: Clear all timers and restore the coordinator when tests complete |
| 81 | +5. **Fallback**: Fall back to normal test execution if conditions aren't met |
| 82 | + |
| 83 | +### PHPUnit Patch |
| 84 | + |
| 85 | +This 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 automatically applied when the package autoloads. |
| 86 | + |
| 87 | +## Requirements |
| 88 | + |
| 89 | +- PHP >= 8.0 |
| 90 | +- PHPUnit >= 10.0 |
| 91 | +- Swoole extension (when running tests in coroutine mode) |
| 92 | +- Hyperf >= 3.1 (for coordinator functionality) |
| 93 | + |
| 94 | +## Configuration |
| 95 | + |
| 96 | +### Composer Autoload |
| 97 | + |
| 98 | +The package automatically registers its autoload files in composer.json: |
| 99 | + |
| 100 | +```json |
| 101 | +{ |
| 102 | + "autoload-dev": { |
| 103 | + "psr-4": { |
| 104 | + "Your\\Tests\\": "tests/" |
| 105 | + }, |
| 106 | + "files": [ |
| 107 | + "vendor/friendsofhyperf/co-phpunit/phpunit-patch.php" |
| 108 | + ] |
| 109 | + } |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +### PHPUnit Configuration |
| 114 | + |
| 115 | +No special PHPUnit configuration is required. The package works seamlessly with your existing `phpunit.xml` configuration. |
| 116 | + |
| 117 | +## Best Practices |
| 118 | + |
| 119 | +1. **Use for Integration Tests**: This is particularly useful for integration tests that interact with Hyperf's coroutine-aware components |
| 120 | +2. **Enable Selectively**: Not all tests need to run in coroutines. Use `$enableCoroutine = false` for unit tests that don't require coroutine context |
| 121 | +3. **Test Isolation**: The package automatically cleans up timers and coordinator state between tests |
| 122 | +4. **Performance**: Tests running in coroutines may have slightly different performance characteristics |
| 123 | + |
| 124 | +## Example: Testing Hyperf Services |
| 125 | + |
| 126 | +```php |
| 127 | +<?php |
| 128 | + |
| 129 | +namespace App\Tests; |
| 130 | + |
| 131 | +use FriendsOfHyperf\CoPHPUnit\Concerns\RunTestsInCoroutine; |
| 132 | +use Hyperf\Context\ApplicationContext; |
| 133 | +use PHPUnit\Framework\TestCase; |
| 134 | + |
| 135 | +class ServiceTest extends TestCase |
| 136 | +{ |
| 137 | + use RunTestsInCoroutine; |
| 138 | + |
| 139 | + public function testServiceWithCoroutineContext() |
| 140 | + { |
| 141 | + // Get service from container |
| 142 | + $service = ApplicationContext::getContainer()->get(YourService::class); |
| 143 | + |
| 144 | + // Test methods that use coroutine context |
| 145 | + $result = $service->asyncOperation(); |
| 146 | + |
| 147 | + $this->assertNotNull($result); |
| 148 | + } |
| 149 | + |
| 150 | + public function testDatabaseConnection() |
| 151 | + { |
| 152 | + // Test database operations that require connection pools |
| 153 | + $result = Db::table('users')->first(); |
| 154 | + |
| 155 | + $this->assertIsArray($result); |
| 156 | + } |
| 157 | +} |
| 158 | +``` |
| 159 | + |
| 160 | +## Troubleshooting |
| 161 | + |
| 162 | +### Tests Hanging or Timing Out |
| 163 | + |
| 164 | +If tests hang, ensure: |
| 165 | +- All async operations are properly awaited |
| 166 | +- No infinite loops exist in coroutine callbacks |
| 167 | +- Timers are cleared during test teardown |
| 168 | + |
| 169 | +### "Call to a member function on null" |
| 170 | + |
| 171 | +This typically indicates coroutine context is unavailable. Ensure: |
| 172 | +- Swoole extension is installed and enabled |
| 173 | +- The `RunTestsInCoroutine` trait is included |
| 174 | +- `$enableCoroutine` is set to `true` |
| 175 | + |
| 176 | +### PHPUnit Version Compatibility |
| 177 | + |
| 178 | +This package supports PHPUnit 10.x, 11.x, and 12.x. Make sure your PHPUnit version is compatible. |
0 commit comments