Phpunit Extras Laravel Package

Getting Started

Minimal Setup

1. Installation Add via Composer:

   composer require --dev rybakit/phpunit-extras
   

   Requires PHPUnit 9.x+ and PHP 8.0+.

2. First Use Case Annotate a test method with @dataProvider (if using custom providers) or leverage built-in annotations like @expectException (though PHPUnit already supports this—see below for extras).

   Example:

   use Rybakit\PHPUnitExtras\Annotations\DataProvider;
   
   class MyTest extends \PHPUnit\Framework\TestCase
   {
       #[DataProvider('myProvider')]
       public function testSomething($input, $expected)
       {
           $this->assertEquals($expected, someFunction($input));
       }
   
       public function myProvider()
       {
           return [
               ['input1', 'expected1'],
               ['input2', 'expected2'],
           ];
       }
   }
   

3. Where to Look First

   • Annotations: Check src/Annotations/ for available annotations (e.g., @DataProvider, @SkipIf, @Timeout).
   • Expectations: Review src/Expectations/ for custom assertions (e.g., isIterableLike, containsOnlyInstancesOf).
   • Traits: Explore src/Traits/ for reusable test logic (e.g., HasAssertions, HasDataProviders).

Implementation Patterns

Common Workflows

1. Data-Driven Testing Use @DataProvider or @DataProviders (plural) to centralize test data:

   #[DataProviders([
       new DataProvider('provider1'),
       new DataProvider('provider2'),
   ])]
   public function testWithMultipleProviders($data) { ... }
   

2. Conditional Skipping Skip tests dynamically with @SkipIf:

   #[SkipIf(condition: 'app()->environment("production")')]
   public function testOnlyInDev() { ... }
   

3. Custom Assertions Replace verbose assertions with fluent methods:

   $this->assert->containsOnlyInstancesOf(stdClass::class, $collection);
   

4. Timeouts Enforce execution limits:

   #[Timeout(seconds: 2)]
   public function testFastOperation() { ... }
   

Integration Tips

• Laravel-Specific: Combine with Laravel’s RefreshDatabase or MigrateFresh traits for seamless test isolation.
• CI/CD: Use @SkipIf to bypass flaky tests in CI:

  #[SkipIf(condition: 'getenv("CI") === false')]
  public function testFlakyInLocal() { ... }
  

• Legacy Code: Override PHPUnit’s getDataProvider() to migrate from @dataProvider to @DataProvider incrementally.

Gotchas and Tips

Pitfalls

1. Annotation Parsing

   • Ensure annotations are exactly as defined (e.g., @SkipIf(condition: ...) vs. @skipIf).
   • Fix: Use IDE autocompletion (e.g., PHPStorm) or check the package’s Annotation classes.

2. DataProvider Conflicts

   • Mixing @dataProvider (PHPUnit native) and @DataProvider (rybakit) may cause ambiguity.
   • Fix: Stick to one style per test class or namespace.

3. Timeout Precision

   • @Timeout uses seconds (float allowed), but floating-point precision can cause edge cases.
   • Fix: Use integers or round values (e.g., #[Timeout(seconds: 1.5)]).

4. Trait Collisions

   • Overlapping traits (e.g., HasAssertions + custom assertions) may shadow methods.
   • Fix: Use fully qualified trait names or alias methods.

Debugging Tips

• Enable Verbose Output: Run tests with -v to see skipped/timeout reasons:

  phpunit -v
  

• Check Annotations: Use phpunit --debug to inspect parsed annotations.
• Isolate Tests: Temporarily remove @DataProviders to debug provider issues.

Extension Points

1. Custom Annotations Extend Rybakit\PHPUnitExtras\Annotations\Annotation to create your own:

   class MyCustomAnnotation extends Annotation { ... }
   

2. Expectation Helpers Add to src/Expectations/Assertions.php:

   public function containsOnlyKeys(array $keys, array $array) { ... }
   

3. Global Setup Use setUpBeforeClass() to preload data for @DataProvider-driven tests:

   public static function setUpBeforeClass(): void
   {
       self::$sharedData = require __DIR__.'/data.php';
   }
   

4. Laravel Integration Bind the package’s services in TestCase:

   use Rybakit\PHPUnitExtras\PHPUnitExtras;
   
   protected function setUp(): void
   {
       $this->phpUnitExtras = new PHPUnitExtras();
   }