Rector Pest Laravel Package

Technical Evaluation

Architecture Fit

• Laravel/PHP Ecosystem Alignment: The package is highly relevant for Laravel projects using Pest as their testing framework. Pest is a modern alternative to PHPUnit, widely adopted in Laravel ecosystems (especially with Laravel 10+), and this package directly addresses:
  • Code quality improvements (e.g., chaining expect() calls, leveraging Pest matchers).
  • Migration paths (PHPUnit → Pest, Pest v2→v3→v4).
  • Laravel-specific optimizations (e.g., Str:: assertions → Pest string matchers).
• Rector Integration: Leverages Rector’s rule-based refactoring, which is a standard tool in Laravel/PHP for automated code modernization. The package extends Rector’s existing Pest support (e.g., rector/rector-pest by Spatie) with semantic-aware rules, reducing false positives/negatives.
• Modular Design: Rule sets (e.g., PEST_CODE_QUALITY, PEST_MIGRATION) allow granular adoption, aligning with Laravel’s preference for incremental, non-breaking changes.

Integration Feasibility

• Low Friction: Requires only composer require --dev mrpunyapal/rector-pest and minimal rector.php configuration. No runtime dependencies beyond Rector/Pest.
• Isolated Scope: Operates only on test files (configurable paths), avoiding risk to production code.
• Backward Compatibility: Rules are opt-in (e.g., PEST_MIGRATION requires manual review), mitigating regression risks.
• Toolchain Synergy: Works seamlessly with:
  • Laravel’s built-in Pest support (since Laravel 10).
  • CI/CD pipelines (e.g., run as a pre-commit hook or PR check).
  • Static analysis tools (e.g., PestStan, PHPStan).

Technical Risk

Key Questions for TPM

1. Adoption Scope:

   • Should this be applied globally (all tests) or selectively (e.g., only new features)?
   • How will the team validate changes (e.g., test coverage, manual review)?

2. Version Strategy:

   • Is the project locked to a Pest version, or should upgrades be prioritized?
   • Should UP_TO_PEST_40 be applied now, or phased with PEST_30 first?

3. Toolchain Integration:

   • How will this fit with existing static analysis (PHPStan, PestStan) or linters (PSR-12)?
   • Should Rector runs be gated in CI (e.g., fail builds on changes)?

4. Maintenance:

   • Who will update Rector/Pest dependencies as new versions release?
   • Should this be vendor-locked (e.g., composer require --dev) or managed centrally (e.g., via tools/ repo)?

5. Edge Cases:

   • Are there legacy PHPUnit tests that need migration? If so, should PEST_MIGRATION be used?
   • Does the team use Pest Browser or other plugins that could benefit from PEST_BROWSER?

Integration Approach

Stack Fit

• Primary Stack: Laravel 10+ with Pest (v2/v3/v4) and Rector (v2.0+).
• Secondary Stack: Projects using:
  • PHPUnit → Pest migration (PEST_MIGRATION).
  • Pest Browser (PEST_BROWSER).
  • Custom Pest assertions needing optimization (PEST_CODE_QUALITY/PEST_CHAIN).
• Anti-Patterns:
  • Avoid if using non-standard Pest configurations (e.g., custom matchers).
  • Not suitable for projects heavily coupled to PHPUnit without migration plans.

Migration Path

Compatibility

• PHP Version: Requires PHP 8.2+ (aligns with Laravel 10+).
• Rector Version: v2.0+ (check composer.json; update if needed).
• Pest Version:
  • UP_TO_PEST_30: Targets v2→v3.
  • UP_TO_PEST_40: Targets v2/v3→v4.
  • Avoid mixing sets (e.g., don’t apply PEST_30 + PEST_40).
• Dependencies:
  • PEST_BROWSER: Requires pestphp/pest-plugin-browser.
  • PEST_LARAVEL: Requires illuminate/support.

Sequencing

1. Pre-requisites:
   • Update rector/rector to v2.4.1+ (for chaining formatting).
   • Ensure Pest is installed (composer require pestphp/pest --dev).
2. Configuration:
   • Add to composer.json:

     "require-dev": {
       "mrpunyapal/rector-pest": "^1.0"
     }
     

   • Create/update rector.php:

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

3. Execution:
   • Dry run: vendor/bin/rector process --dry-run.
   • Apply: vendor/bin/rector process.
4. Post-Processing:
   • Commit changes with a message like:

     chore: apply rector-pest code quality rules (PEST_CODE_QUALITY, PEST_CHAIN)
     

   • Update CI to include Rector (e.g., GitHub Actions):

     - name: Run Rector
       run: composer run rector
     

Operational Impact

Maintenance

• Dependency Management:
  • Proactive: Pin mrpunyapal/rector-pest to a version (e.g., ^1.0) to avoid surprises.
  • Reactive: Monitor for updates via Packagist or GitHub releases.
• Rule Updates:
  • New Pest versions may require new rule sets (e.g., UP_TO_PEST_50).
  • Action: Schedule quarterly audits to align with Pest/Rector updates.
• Custom Rules:
  • If extending (e.g., adding PEST_LARAVEL), document in rector.php:

    // Custom rules