Rector Rules Laravel Package

Technical Evaluation

Architecture Fit

• Leverages Rector’s Static Analysis: The new PHPUnit\ReplaceTestAttributeWithTestPrefixRector rule extends the package’s focus on modernizing PHP test suites, aligning with Laravel’s heavy reliance on PHPUnit/Pest for testing. This is particularly relevant for Laravel projects adopting PHPUnit 9+ or Pest 2+, where test attributes (e.g., @test) are being replaced with #[Test] syntax.
• Laravel-Specific Synergy:
  • PHPUnit/Pest Integration: Laravel’s testing ecosystem (e.g., laravel/pint, nunomaduro/collision) often uses PHPUnit; this rule automates migration to modern test syntax, reducing manual effort during PHPUnit upgrades.
  • Test Organization: The rule can enforce consistent test prefixes (e.g., test_ or it_), improving readability in Laravel’s test suites (e.g., tests/Feature/).
• Non-Breaking Addition: The rule is structural (replaces annotations with attributes) and does not alter test logic, making it low-risk for Laravel projects.

Integration Feasibility

• Composer Integration: Remains a dev-dependency, with no impact on production. Add via:

  composer require --dev ergebnis/rector-rules:^1.17.0
  

• Configuration: Update rector.php to include the new rule:

  use Ergebnis\Rector\Rules;
  
  return static function (RectorConfig $config): void {
      $config->rule(Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector::class);
  };
  

• Laravel-Specific Hooks:
  • Artisan Command: Extend the existing rector:refactor command to include test directories:

    php artisan rector:refactor --dir=tests
    

  • CI/CD: Add to GitHub Actions as a pre-test step to validate attribute migration:

    - name: Migrate Test Attributes
      run: composer rector -- --dir=tests
    

Technical Risk

• False Positives/Negatives:
  • Custom Test Annotations: Laravel projects may use custom PHPUnit annotations (e.g., @group, @dataProvider). Mitigation: Exclude non-standard annotations via rule configuration or .rectorignore.
  • Pest Framework: Pest 2+ uses a different syntax (it(), test()). Mitigation: Disable the rule for Pest files or use Pest’s native migration tools.
• Dependency Conflicts:
  • PHPUnit Version: Requires PHPUnit 9+ for #[Test] support. Mitigation: Add a composer.json constraint:

    "require-dev": {
        "phpunit/phpunit": "^9.0"
    }
    

• Rule Overlap:
  • Pest Migration Tools: Pest provides its own migration utilities. Mitigation: Prioritize Pest’s tools for Pest-specific projects; use Rector for PHPUnit-only suites.
• Performance:
  • Processing large test suites (e.g., tests/Feature/ with 1,000+ files) may slow CI. Mitigation: Run incrementally or cache results.

Key Questions

1. Adoption Scope:
   • Should the rule target all test files or only specific directories (e.g., tests/Unit/)?
   • How will we handle Pest vs. PHPUnit coexistence in the codebase?
2. Testing Strategy:
   • How will we validate that migrated tests (e.g., @test → #[Test]) retain identical behavior? (e.g., parallel test execution).
3. CI/CD Integration:
   • Should the rule fail builds on unmigrated test attributes, or log warnings?
   • How will we handle flaky migrations (e.g., race conditions in test attribute parsing)?
4. Rule Customization:
   • Do we need to extend the rule to support Laravel-specific test annotations (e.g., @uses, @runInSeparateProcess)?
   • Should we disable the rule for legacy tests marked with @skip?
5. Maintenance:
   • Who will update the rule configuration if PHPUnit introduces new attribute syntax (e.g., #[Before])?
6. Documentation:
   • How will we communicate the migration to developers (e.g., PR templates, release notes)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • PHPUnit/Pest: Native support for test attribute migration. Pest 2+ may require separate handling.
  • Composer: No conflicts with Laravel’s dev-dependency model.
  • IDE Support: Updated attributes will reflect in PHPStorm/VSCode with PHPUnit plugin updates.
• Toolchain Compatibility:
  • Static Analyzers: Works alongside PHPStan/Psalm (no syntax conflicts with #[Test]).
  • Linters: Complements php-cs-fixer for combined test formatting/migration pipelines.
  • Laravel Testing Packages: No conflicts with laravel/pint or nunomaduro/collision.

Migration Path

1. Pilot Phase:
   • Test the rule on a single test file or module (e.g., tests/Unit/ExampleTest.php).
   • Use --dry-run to preview changes:

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

2. Incremental Rollout:
   • Start with PHPUnit-only tests (exclude Pest files via .rectorignore).
   • Example rector.php configuration:

     $config->ruleWithConfiguration(
         Rules\PHPUnit\ReplaceTestAttributeWithTestPrefixRector::class,
         [
             'attribute' => 'test', // Migrate `@test` to `#[Test]`
             'prefix' => 'test_',   // Optional: Enforce `test_*` method naming
         ]
     );
     

3. CI/CD Integration:
   • Add to composer.json scripts:

     "scripts": {
         "rector:tests": "rector process tests --level=all",
         "rector:tests:check": "rector process tests --dry-run --level=all"
     }
     

   • Configure GitHub Actions:

     - name: Migrate Test Attributes
       run: composer rector:tests:check
     

4. Laravel-Specific Adaptations:
   • Pest Framework: Exclude Pest files:

     # .rectorignore
     tests/Unit/Pest/
     

   • Custom Annotations: Disable the rule for files with @group or @dataProvider:

     $config->skip([
         __DIR__ . '/tests/Feature/Groups/*',
     ]);
     

Compatibility

• Laravel Versions:
  • Laravel 9/10: Full compatibility (PHPUnit 9+ required).
  • Laravel 8: Partial compatibility (PHPUnit 8.x may not support #[Test]).
• Package Dependencies:
  • Ensure phpunit/phpunit:^9.0 is in composer.json.
  • Test with nunomaduro/collision or laravel/pint to avoid conflicts.
• Custom Code:
  • Legacy Tests: Use --ignore to skip files with @skip or custom annotations.

Sequencing

1. Pre-Refactoring:
   • Backup test suites and run tests to establish a baseline.
   • Update composer.json to require PHPUnit 9+.
2. Refactoring:
   • Start with non-critical tests (e.g., tests/Unit/).
   • Avoid feature tests until migration is validated.
3. Post-Refactoring:
   • Run tests with --testdox-html to verify coverage.
   • Update documentation to reflect #[Test] syntax.
4. Monitoring:
   • Track CI runtime for test attribute migration.
   • Gather feedback on rule effectiveness from QA teams.

Operational Impact

Maintenance

• Rule Updates:
  • Monitor ergebnis/rector-rules for PHPUnit attribute syntax changes (e.g., #[Test] deprecation).
  • Schedule quarterly reviews to adopt new rule versions.
• Configuration Drift:
  • Centralize rector.php in a shared template (e.g., Laravel monorepo or laravel/package).
  • Document rule exclusions (e.g., Pest files, custom annotations) in README.md.
• Deprecation:
  • Plan to deprecate @test annotations post-migration (e.g., via php-cs-fixer).

Support

• Developer Onboarding:
  • Add a RECTOR_RULES.md file explaining test attribute migration.
  • Include a pre-commit hook to warn about unmigrated test attributes.
• Troubleshooting:
  • Provide a debug script to identify problematic test files: