Rector Pest Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require --dev mrpunyapal/rector-pest
   

2. Configure Rector in rector.php:

   use RectorPest\Set\PestSetList;
   use Rector\Config\RectorConfig;
   
   return RectorConfig::configure()
       ->withPaths([__DIR__ . '/tests'])
       ->withSets([PestSetList::PEST_CODE_QUALITY]);
   

3. Run Rector (dry-run first):

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

First Use Case

Convert verbose expect() calls to chained assertions for cleaner tests:

// Before
expect($user)->toBeInstanceOf(User::class);
expect($user->name)->toBe('John');
expect($user->email)->toBe('john@example.com');

// After (with PEST_CHAIN)
expect($user)
    ->toBeInstanceOf(User::class)
    ->name->toBe('John')
    ->email->toBe('john@example.com');

Implementation Patterns

Workflow Integration

1. Version Upgrades: Use PestLevelSetList to migrate between major Pest versions:

   // rector.php
   return RectorConfig::configure()
       ->withSets([PestLevelSetList::UP_TO_PEST_40]);
   

   • Runs all version-specific rules (e.g., v2→v3 + v3→v4).

2. Selective Rule Application: Target specific test files or directories:

   ->withPaths([
       __DIR__ . '/tests/Unit',
       __DIR__ . '/tests/Feature',
   ]);
   

3. PHPUnit-to-Pest Migration: Apply PEST_MIGRATION incrementally:

   ->withSets([PestSetList::PEST_MIGRATION]);
   

   • Tip: Run dry-run first to review changes (e.g., assertEquals() → expect()->toEqual()).

4. Browser Testing Optimization: For pestphp/pest-plugin-browser, use PEST_BROWSER:

   ->withPaths([__DIR__ . '/tests/Browser'])
       ->withSets([PestSetList::PEST_BROWSER]);
   

   • Converts expect($page->value()) to $page->assertValue().

5. Custom Rule Chaining: Combine sets for layered improvements:

   ->withSets([
       PestSetList::PEST_CODE_QUALITY, // Readability
       PestSetList::PEST_CHAIN,        // Chaining
       PestSetList::PEST_LARAVEL,      // Laravel-specific (e.g., `Str::` → matchers)
   ]);
   

CI/CD Integration

• Pre-commit Hook: Use rector process --dry-run in CI to block breaking changes.
• GitHub Actions Example:

  - name: Run Rector
    run: vendor/bin/rector process --dry-run
  

Gotchas and Tips

Common Pitfalls

1. False Positives in Chaining:

   • Issue: PEST_CHAIN may merge unrelated expect() calls if variables are reused.
   • Fix: Exclude specific files or use individual rules:

     ->withRules([ChainExpectCallsRector::class])
         ->withExcludedPaths([__DIR__ . '/tests/EdgeCases']);
     

2. Laravel-Specific Rules:

   • PEST_LARAVEL requires illuminate/support. If missing, Rector will fail silently.
   • Fix: Add composer require illuminate/support or exclude the set.

3. Browser Plugin Dependencies:

   • PEST_BROWSER rules only work if pestphp/pest-plugin-browser is installed.
   • Fix: Verify the plugin is in composer.json before running.

4. Semantic Ambiguity:

   • Rules like ConvertAssertToExpectRector may misinterpret custom assertions.
   • Fix: Review changes manually or exclude problematic files.

5. Formatting Quirks:

   • Chaining formatting (e.g., line breaks) depends on Rector 2.4.1+.
   • Fix: Update Rector or manually adjust formatting post-run.

Debugging Tips

• Dry-Run First:

  vendor/bin/rector process --dry-run --format=diff
  

  • Outputs a diff to preview changes.

• Verbose Logging:

  vendor/bin/rector process --verbose
  

  • Shows skipped rules and excluded files.

• Rule-Specific Debugging: Use --rules to isolate issues:

  vendor/bin/rector process --rules=ChainExpectCallsRector
  

Extension Points

1. Custom Rules: Extend the package by creating your own Rector rules (e.g., for project-specific assertions):

   use Rector\Core\Contract\Rector\RectorInterface;
   
   class CustomPestRector implements RectorInterface { ... }
   

   • Register in rector.php:

     ->withRules([CustomPestRector::class]);
     

2. Semantic Interop: Leverage the semantic registry to add custom diagnostics:

   // Example: Add a new issue type
   $semanticRegistry->addIssue('CustomPestIssue', [
       'description' => 'Custom Pest anti-pattern',
       'fix' => fn($node) => $node->setMethod('customAssert'),
   ]);
   

3. Conditional Rule Application: Use Rector’s Condition to apply rules selectively:

   use Rector\Core\Contract\Rector\Condition\ConditionInterface;
   
   class OnlyInUnitTestsCondition implements ConditionInterface { ... }
   

   • Attach to rules:

     ->withRules([
         ChainExpectCallsRector::class => [OnlyInUnitTestsCondition::class],
     ]);
     

Performance

• Exclude Large Files:

  ->withExcludedPaths([__DIR__ . '/tests/Performance/*']);
  

• Parallel Processing: Use --parallel for large codebases:

  vendor/bin/rector process --parallel