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. Version Alignment (as of 14.5.0): The package tracks a modern toolchain and pulls it in transitively. Before upgrading, confirm your project matches:

   • phpunit/phpunit ^13.4.1
   • wyrihaximus/phpstan-rules-wrapper ^14.10.1
   • wyrihaximus/qa-tooling-wrapper ^2.4.0
   • wyrihaximus/makefiles ^0.15.2

   composer require --dev wyrihaximus/test-utilities:^14.5 phpunit/phpunit:^13.4
   

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

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

4. 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
   }
   

5. 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 (^14.10.1 as of 14.5.0) for project-specific rules.

3. Shared QA Tooling: The package rides on wyrihaximus/qa-tooling-wrapper (^2.4.0), so lint/static-analysis binaries arrive pinned and pre-wired — prefer those entry points over hand-rolled vendor/bin invocations so your CI matches the package’s expectations.

CI Workflows

1. Reusable GitHub Actions: The 14.5.0 line is validated against WyriHaximus/github-workflows v1.1.2. If you copy CI from this repo, pin to @v1.1.2 rather than @main:

   - uses: WyriHaximus/github-workflows/.github/workflows/[email protected]
   

2. Renovate-Driven Updates: Expect frequent patch bumps of the whole toolchain (this release was 10 dependency PRs, 0 code changes). Batch them — a lockfile-only update should never require code changes.

Gotchas and Tips

Pitfalls

1. Major Version Jump (13 → 14): The package went from 13.2.0 to 14.5.0. Major bumps in this repo historically mean "toolchain alignment" (PHPUnit major, PHPStan wrapper major), not API redesign — but your own phpunit.xml schema, Rector sets, and PHPStan baseline formats must be upgraded in lockstep.

   • Fix: Upgrade to ^14.5 in a dedicated branch, run composer update --with-all-dependencies, then fix phpunit.xml and baseline issues before touching application code.

2. Namespace Collisions:

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

3. Rector Version Pinning:

   • The package pins Rector and PHPStan-wrapper versions to avoid conflicts (e.g., icanhaxstring/composer-unused).
   • Tip: Check composer.json for pinned versions if custom Rector rules fail. wyrihaximus/phpstan-rules-wrapper moves fast (14.9.0 → 14.10.1 inside this single release), so a composer update can silently change static-analysis results.

4. 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>
     

   • PHPUnit 13 changed the extension registration surface; if the extension silently no-ops, verify the <extensions> element is present (it is not implied by a composer require).

5. Makefile Targets: wyrihaximus/makefiles ^0.15.2 is a dev convenience only — do not depend on its targets in production pipelines you don't control. Copy the recipes into your own Makefile if you need stability.

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
     

   • After a wrapper bump within the same major (e.g. 14.9 → 14.10), diff vendor/wyrihaximus/phpstan-rules-wrapper/src before regenerating a baseline, so you don't bake in newly-introduced errors.

4. "Changed Nothing But CI Broke": This release contains zero code changes — a red build after upgrading is almost always a transitive toolchain bump. composer why-not phpunit/phpunit ^13.4 is the fastest first move.

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());
   }