Bridge Rector Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require --dev testo/bridge-rector
   

   Ensure rector.php exists in your project root (create if missing) and include the package rules:

   return [
       'rules' => [
           \Testo\BridgeRector\Set\TestSuiteBridgeSet::class,
       ],
   ];
   

2. First Use Case Run Rector to convert a single test file (e.g., PEST → PHPUnit):

   vendor/bin/rector process tests/ExampleTest.php --dry-run
   

   Verify the output matches your target framework’s syntax.

3. Where to Look First

   • Rector Docs for core usage.
   • Bridge-Rector Rules for supported conversions (e.g., test() → public function test_()).
   • Test files in the package’s tests directory for real-world examples.

Implementation Patterns

Workflows

1. Incremental Migration

   • Convert test files in batches using --paths:

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

   • Use --exclude to skip legacy tests until ready:

     vendor/bin/rector process tests/ --exclude="Legacy/*"
     

2. CI/CD Integration

   • Add a Rector step to your pipeline (e.g., GitHub Actions):

     - name: Migrate tests
       run: vendor/bin/rector process tests/ --dry-run
     

   • Fail builds on dry-run mismatches to enforce consistency.

3. Custom Rule Extensions

   • Extend TestSuiteBridgeSet by creating a custom rule set:

     // rector.php
     return [
         'sets' => [
             TestSuiteBridgeSet::class,
             \App\CustomTestRectorSet::class, // Your custom rules
         ],
     ];
     

Integration Tips

• Pre-commit Hooks: Use rector to auto-fix tests before commits (via tools like Husky).
• IDE Support: Configure PHPStorm to run Rector on save (via PHP Inspections).
• Parallel Processing: For large suites, split tests by namespace and run Rector in parallel:

  vendor/bin/rector process tests/Unit/ tests/Feature/ --parallel
  

Gotchas and Tips

Pitfalls

1. False Positives in Dry Runs

   • Rector may flag intentional syntax (e.g., test() used in non-test contexts). Use --exclude-paths to ignore specific files/directories.
   • Fix: Manually review or extend rules to whitelist patterns.

2. Stateful Transformations

   • Some rules (e.g., converting beforeEach to setUp) rely on file structure. Run Rector on the entire test suite first, not individual files.
   • Fix: Use --paths="tests/" to process all tests at once.

3. Dependency Conflicts

   • Bridge-Rector may conflict with other Rector rules (e.g., PHPUnit or PEST sets). Explicitly order sets in rector.php:

     return [
         'sets' => [
             \Rector\PHPUnit\Set\PHPUnitSet::class, // Base rules first
             TestSuiteBridgeSet::class,             // Override last
         ],
     ];
     

4. Unsupported Features

   • Not all test frameworks support 100% parity (e.g., PEST’s expect() vs. PHPUnit’s assertEquals()). Review the rule list for gaps.
   • Fix: Manually refactor unsupported cases post-Rector.

Debugging

• Verbose Output: Use --verbose to see which rules are applied:

  vendor/bin/rector process tests/ --verbose
  

• Rule Isolation: Test individual rules with --rule=TestSuiteBridgeSet\ConvertTestFunctionRule.
• Git Diff: Compare dry-run output with git diff to spot unexpected changes:

  vendor/bin/rector process tests/ --dry-run | git apply --check
  

Extension Points

1. Custom Rules

   • Extend AbstractTestSuiteBridgeRule to handle framework-specific quirks:

     use Testo\BridgeRector\Rule\AbstractTestSuiteBridgeRule;
     
     final class CustomPestToPHPUnitRule extends AbstractTestSuiteBridgeRule {
         public function getRuleDefinition(): NodeTypeResolution {
             return new NodeTypeResolution(
                 PestTestCase::class,
                 fn(PestTestCase $node) => $this->transform($node)
             );
         }
     }
     

2. Configuration Overrides

   • Disable specific rules via rector.php:

     return [
         'rules' => [
             TestSuiteBridgeSet::class => [
                 \Testo\BridgeRector\Rule\ConvertTestFunctionRule::class => false,
             ],
         ],
     ];
     

3. Post-Processing

   • Chain Rector with other tools (e.g., php-cs-fixer) to normalize code after conversion:

     vendor/bin/rector process tests/ && vendor/bin/php-cs-fixer fix tests/