Test Utilities Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wyrihaximus/test-utilities --dev
   

   Add to your composer.json under require-dev if not using global install.

2. PHPUnit Integration: Extend your test case with WyriHaximus\TestUtilities\TestCase:

   use WyriHaximus\TestUtilities\TestCase;
   
   class MyTest extends TestCase
   {
       // Tests here
   }
   

3. First Use Case: Leverage the built-in random namespace/directory utilities for file storage tests:

   public function testFileStorage()
   {
       $filePath = $this->getRandomFilePath();
       // Use $filePath in your test
   }
   

4. Rector Configuration: Use the provided RectorConfig for migrations:

   // rector.php
   use WyriHaximus\TestUtilities\RectorConfig;
   
   return RectorConfig::configure(__DIR__ . '/../src');
   

Implementation Patterns

PHPUnit Workflows

1. Test Isolation: Use $this->getRandomNamespace() and $this->getRandomDirectory() to avoid test pollution:

   $namespace = $this->getRandomNamespace();
   $this->assertNamespaceIsUnique($namespace);
   

2. Mocking & Factories: Combine with Laravel’s createMock() or factories for complex test data:

   $mock = $this->createMock(User::class);
   $mock->method('getName')->willReturn($this->getRandomString());
   

3. Assertion Helpers: Utilize built-in assertions like assertNamespaceIsUnique() or assertDirectoryIsEmpty().

Rector Integration

1. Automated Refactoring: Run Rector with the provided config to standardize docblocks to attributes:

   vendor/bin/rector process src --dry-run
   

2. Custom Rules: Extend RectorConfig for project-specific rules:

   return RectorConfig::configure(__DIR__)
       ->withRule(SetTypehintRule::class)
       ->withRule(AddFinalPrivateRule::class);
   

PHPStan Integration

1. Extension Config: Use the package’s PHPStan extension for stricter type checking:

   // phpstan.neon
   includes:
       - vendor/wyrihaximus/test-utilities/phpstan.neon
   

2. Custom Rules: Combine with wyrihaximus/phpstan-rules-wrapper for project-specific rules.

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • Random namespaces/directories may conflict with existing project structure.
   • Fix: Validate uniqueness with $this->assertNamespaceIsUnique().

2. Rector Version Pinning:

   • The package pins Rector versions to avoid conflicts (e.g., icanhaxstring/composer-unused).
   • Tip: Check composer.json for pinned versions if custom Rector rules fail.

3. PHPUnit Slow Test Detection:

   • The package includes ergebnis/phpunit-slow-test-detector by default.
   • Tip: Configure thresholds in phpunit.xml:

     <phpunit ...>
         <extensions>
             <extension class="Ergebnis\PhpunitSlowTestDetector\SlowTestDetectorExtension"/>
         </extensions>
     </phpunit>
     

Debugging Tips

1. Randomness Issues:

   • Use $this->getRandomString() with a seed for reproducibility:

     $this->seedRandom(1234);
     $randomString = $this->getRandomString();
     

2. File/Directory Permissions:

   • Ensure temporary directories (e.g., $this->getRandomDirectory()) have write permissions:

     $dir = $this->getRandomDirectory();
     $this->assertDirectoryIsWritable($dir);
     

3. PHPStan False Positives:

   • Extend the PHPStan config to ignore specific rules:

     ignoreErrors:
         - WyriHaximus\TestUtilities\Rules\*.php
     

Extension Points

1. Custom Test Case: Override TestCase methods for project-specific behavior:

   class CustomTestCase extends TestCase
   {
       protected function getRandomNamespace(): string
       {
           return 'Custom\\' . parent::getRandomNamespace();
       }
   }
   

2. Rector Rule Sets: Create custom rule sets by extending RectorConfig:

   class ProjectRectorConfig extends RectorConfig
   {
       public function __construct(string $path)
       {
           parent::__construct($path);
           $this->withRule(YourCustomRule::class);
       }
   }
   

3. PHPUnit Listeners: Add custom listeners via setUp():

   protected function setUp(): void
   {
       parent::setUp();
       $this->addListener(new YourCustomListener());
   }