Peststan Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev mrpunyapal/peststan
   

   Ensure phpstan/extension-installer is installed (recommended) or manually add to phpstan.neon:

   includes:
       - vendor/mrpunyapal/peststan/extension.neon
   

2. First Use Case: Run PHPStan on your test directory:

   vendor/bin/phpstan analyse tests
   

   PestStan will automatically detect your Pest.php configuration and provide type hints for expect() and $this in test closures.

Implementation Patterns

Core Workflow

1. Type-Safe Expectations:

   // tests/Feature/ExampleTest.php
   it('validates string input', function () {
       expect('hello')->toBeString(); // PHPStan knows this is type-safe
   });
   

2. TestCase Integration:

   // tests/Pest.php
   uses(Tests\TestCase::class)->in('Feature');
   
   // tests/Feature/ExampleTest.php
   it('uses TestCase methods', function () {
       $this->assertDatabaseHas('users', ['email' => 'test@example.com']);
       // PHPStan knows $this is Tests\TestCase
   });
   

3. Dynamic Property Inference:

   beforeEach(function () {
       $this->user = User::factory()->create(); // PHPStan infers User type
   });
   
   it('uses inferred property', function () {
       $this->user->name; // No mixed-type errors
   });
   

Advanced Patterns

1. Assertion Chaining with Type Narrowing:

   /** @var int|string $value */
   $value = getValue();
   
   expect($value)
       ->toBeString() // PHPStan now knows $value is string
       ->toStartWith('test');
   

2. Custom TestCase Methods:

   // tests/Pest.php
   uses(CustomTestCase::class)->in('Unit');
   
   // tests/Unit/ExampleTest.php
   it('uses custom helper')->customHelper();
   

3. Architecture Testing:

   expect('App\Models')
       ->toExtend('Illuminate\Database\Eloquent\Model')
       ->ignoring('App\Models\Legacy');
   

Integration with CI/CD

Add PHPStan to your test suite in phpunit.xml or composer.json:

<phpunit>
    <extensions>
        <extension class="PHPStan\Extensions\PHPUnit\PHPUnitExtension"/>
    </extensions>
</phpunit>

Run in CI:

composer test

Gotchas and Tips

Common Pitfalls

1. Static Closures:

   it('fails', static function () { // ❌ Error: static closure breaks $this binding
       $this->assertTrue(true);
   });
   

   Fix: Remove static or use beforeEach for setup.

2. Missing Property Inference:

   beforeEach(function () {
       $this->user = User::factory()->create(); // ❌ PHPStan may not infer type
   });
   

   Fix: Add @var annotation:

   /** @var User $user */
   $user = User::factory()->create();
   $this->user = $user;
   

3. Incorrect throws() Usage:

   it('fails')->throws(stdClass::class); // ❌ Error: stdClass is not Throwable
   

   Fix: Use a valid Throwable class.

Debugging Tips

1. Enable Verbose Output:

   vendor/bin/phpstan analyse tests --verbose
   

   Helps diagnose misconfigured Pest.php paths.

2. Manual TestCase Override: If auto-detection fails, force it in phpstan.neon:

   parameters:
       peststan:
           testCaseClass: App\Testing\TestCase
   

3. Ignoring Rules: Suppress specific rules in phpstan.neon:

   parameters:
       ignoreErrors:
           - identifier: pest.test.emptyClosure
   

Extension Points

1. Custom Rules: Extend PestDiagnosticIdentifiers to add new static analysis rules.

2. Custom TestCase Methods: Ensure your TestCase class is properly annotated or referenced in Pest.php.

3. Pest Version Compatibility: PestStan supports Pest 3/4/5. Verify your version in composer.json:

   "require-dev": {
       "pestphp/pest": "^5.0"
   }
   

Performance Notes

• Exclude Large Test Files:

  paths:
      - tests/Unit
      - !tests/Integration/LargeTest.php
  

• Cache Results: Use PHPStan’s built-in caching:

  vendor/bin/phpstan analyse tests --generate-baseline