Phpunit Extensions Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev lastdragon-ru/phpunit-extensions
   

   Ensure phpunit.xml includes the autoloader (Composer handles this by default).

2. First Use Case Test a simple array comparison in a PHPUnit test:

   use LastDragon\PHPUnitExtensions\Assert\ArrayAssert;
   
   class ExampleTest extends \PHPUnit\Framework\TestCase
   {
       public function testArrayContains()
       {
           $expected = ['foo', 'bar'];
           $actual = ['foo', 'baz', 'bar'];
   
           ArrayAssert::assertArrayContains($expected, $actual);
       }
   }
   

3. Where to Look First

   • Browse the Assert directory for available extensions.
   • Check the Traits for reusable test logic.
   • Review the Exceptions for custom error handling.

Implementation Patterns

Common Workflows

1. Array Assertions Useful for testing collections, API responses, or database results:

   ArrayAssert::assertArrayContains(['key' => 'value'], $array);
   ArrayAssert::assertArrayNotContains(['key' => 'wrong'], $array);
   ArrayAssert::assertArrayEqualsCanonicalizing($expected, $actual); // Ignores array key order
   

2. Object Assertions Validate object properties or method outputs:

   ObjectAssert::assertPropertyEquals('name', 'John', $user);
   ObjectAssert::assertMethodReturns('getName', 'John', $user);
   

3. Exception Testing Simplify exception assertions:

   ExceptionAssert::assertException(function() {
       throw new \RuntimeException('Test');
   }, \RuntimeException::class, 'Test');
   

4. Database Testing (if extended) If the package includes DB helpers (hypothetical), use:

   DatabaseAssert::assertRecordExists('users', ['email' => 'test@example.com']);
   

5. Custom Assertions Extend existing assertions or create new ones:

   class CustomAssert extends \PHPUnit\Framework\Assert
   {
       public static function assertJsonPathEquals($path, $expected, $actual) {
           // Custom logic
       }
   }
   

Integration Tips

• Combine with Laravel’s Testing Use in Laravel’s HttpTests or FeatureTests for cleaner assertions:

  $response = $this->get('/api/users');
  ArrayAssert::assertArrayContains(['id' => 1], $response->json());
  

• Data Providers Pair with PHPUnit’s @dataProvider for bulk testing:

  public function testMultipleArrays()
  {
      $arrays = [
          [['a'], ['a', 'b']],
          [['x'], ['x', 'y']],
      ];
      foreach ($arrays as $expected) {
          ArrayAssert::assertArrayContains($expected[0], $expected[1]);
      }
  }
  

• Traits for Reusable Logic Use traits in test classes to avoid repetition:

  use LastDragon\PHPUnitExtensions\Traits\AssertTrait;
  
  class UserTest extends TestCase
  {
      use AssertTrait;
  
      public function testUserCreation()
      {
          $this->assertArrayContains(['name' => 'Alice'], $user->toArray());
      }
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts Ensure no naming collisions with existing assertions (e.g., assertEquals vs. custom assertEqualsCanonicalizing).

2. Overriding Default Assertions Avoid shadowing PHPUnit’s built-in methods (e.g., assertArrayHasKey). Prefix custom methods clearly:

   ArrayAssert::assertArrayHasKeyIgnoreCase('Name', $array); // Safer than overriding.
   

3. Performance with Large Arrays Some assertions (e.g., deep array comparisons) may slow tests. Use sparingly for large datasets.

4. Static Analysis Tools Tools like PHPStan may flag unused assertions. Exclude the Assert directory in static analysis configs if needed.

Debugging

• Verbose Failures Enable PHPUnit’s -v flag to see detailed assertion failures:

  phpunit -v tests/Feature/UserTest.php
  

• Custom Exception Messages Extend exceptions for better debugging:

  try {
      ArrayAssert::assertArrayContains(['missing'], $array);
  } catch (\LastDragon\PHPUnitExtensions\Exceptions\ArrayContainsException $e) {
      $this->fail($e->getMessage());
  }
  

Configuration Quirks

• Autoloading Ensure the package is listed in composer.json under require-dev and autoload-dev:

  "autoload-dev": {
      "psr-4": {
          "LastDragon\\PHPUnitExtensions\\": "vendor/lastdragon-ru/phpunit-extensions/src"
      }
  }
  

• PHPUnit Bootstrap If using Laravel’s phpunit.xml, ensure the bootstrap file loads Composer’s autoloader:

  <phpunit>
      <bootstrap>vendor/autoload.php</bootstrap>
  </phpunit>
  

Extension Points

1. Add Custom Assertions Extend the base Assert class or create new classes in src/Assert:

   namespace LastDragon\PHPUnitExtensions\Assert;
   
   class StringAssert extends \PHPUnit\Framework\Assert
   {
       public static function assertContainsIgnoreCase($needle, $haystack) {
           // Custom logic
       }
   }
   

2. Modify Existing Assertions Override methods in a child class (e.g., CustomArrayAssert extends ArrayAssert).

3. Contribute Back Submit PRs to the repo for missing features (e.g., Laravel-specific assertions like assertRedirectsToRoute).

4. Integration with Laravel Mixins For Laravel, create a test macro or mixin:

   use LastDragon\PHPUnitExtensions\Assert\ArrayAssert;
   
   $this->addMacro('assertJsonContains', function ($expected) {
       ArrayAssert::assertArrayContains($expected, $this->response->json());
   });