Pest Plugin Rector Laravel Package

Product Decisions This Supports

• Test-standardization roadmap: This package is the automation lever that determines whether a Pest migration is a credible time-boxed sprint or an unfundable hand-rewrite epic. It converts mechanical PHPUnit patterns — class-based test methods, $this->assert*() calls, setUp/tearDown — into Pest idioms (it(...), expect()->toBe(), beforeEach()), so the roadmap decision becomes "how much of this is automatable?" rather than "how many engineer-weeks to rewrite by hand?"
• Migration sizing and cost estimation: Run the ruleset in dry-run against a representative repository, count changed files, review the diff, and measure the manual-fix rate. That single exercise turns a vague migration into a scoped estimate usable for staffing, sequencing, and roadmap commitments — the highest-value thing a PM can extract from this package before spending anything.
• Build vs. buy vs. fork: Frame the choice three ways: adopt the small MIT ruleset, author custom Rector rules in-house, or fork when coverage gaps appear. Because the surface area is narrow and dev-only, "buy" realistically means "vendor and pin," and "fork" is a legitimate fallback rather than a crisis — MIT licensing keeps that option open.
• Convention enforcement as platform capability: If Rector already runs in CI, adding a Pest ruleset extends an existing quality gate. This supports a decision to enforce assertion style, lifecycle hooks, and test conventions mechanically instead of relying on review comments and team discipline — a durable platform investment, not a one-off migration chore.
• Engineering-enablement investment priority: The value compounds when the same PHPUnit-to-Pest conversion repeats across repos or acquired teams. That's the signal to fund codemod/DX work centrally rather than letting each team absorb its own migration cost.
• Representative use cases: Bulk conversion of class-based tests to Pest's functional style; setUp/tearDown to lifecycle hooks; assertion-syntax normalization; onboarding legacy apps or acquired teams onto one testing standard; reducing review overhead during a framework transition.

When to Consider This Package

Consider it when most of these hold:

• Rector is already in the pipeline, or you're willing to add it. This is an extension of Rector, not a standalone migration product — without Rector there is no product here.
• You are actively migrating PHPUnit to Pest, or standardizing conventions across a large existing Pest suite.
• The legacy suite is large enough that manual conversion cost dominates the cost of evaluating, pinning, and babysitting a low-adoption tool.
• You can treat it as source, not a supported product: a named owner, pinned versions, every generated diff reviewed, and an accepted possibility of forking or maintaining individual rules.
• You can validate against real idioms first: dry-run on one module, compare test counts and coverage, measure the automated-vs-manual fix ratio.

Look elsewhere or defer when:

• The suite is greenfield or small. Hand-conversion is likely faster than evaluating rule coverage and managing another dev dependency.
• There is no Pest migration intent, or the organization is staying on PHPUnit.
• You need vendor support, an SLA, or strong maintenance signals. 16 stars and 0 dependents is a genuine adoption risk — compatibility with future Pest/Rector majors rests on limited community pressure and goodwill. Treat the source as the documentation, because it effectively is.
• You operate in a regulated or supply-chain-sensitive environment where unmaintained dev dependencies require formal justification.
• The migration leans heavily on mocks, custom base classes, @depends, complex data providers, or lifecycle ordering. Expect a meaningful manual tail — budget roughly 30% manual cleanup on a real suite. The plugin is an accelerator, not an oracle, and silent semantic drift (weakened assertions, flattened data providers, reordered setUp/tearDown) is the real risk.

Evaluation checklist before committing: rule coverage against your actual test idioms; supported Pest/PHP/Rector version matrix; presence of the repo's own tests; release cadence and issue responsiveness; license compatibility (MIT is permissive); contributor bus factor; and a named internal owner for pinning, upgrades, and potential fork maintenance.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed, developer-only utility that automates a mechanical portion of test modernization. It never ships to production and adds no runtime dependency, so downside is bounded to engineering time; the upside is converting part of a multi-week manual rewrite into reviewable automated diffs. Recommendation: fund a time-boxed pilot on one representative repository, measure the automated-vs-manual fix ratio and any coverage drift, then decide the broader migration on real data rather than vendor claims or tool reputation.

To engineering leadership: It plugs into the Rector pipeline you likely already run and applies codemods that move PHPUnit-style tests toward Pest idioms. Run it in dry-run on a branch, review the generated diff, and gate merges on tests, test counts, and coverage against a green baseline. Because adoption is minimal, plan for it as a vendored, pinned tool with a named owner, and budget a small allowance for forking or authoring custom rules. Practical guardrails: scope withPaths() to explicit test directories (never the repo root — it will happily rewrite app/), order the Pest set after PHPUnit/PHP sets, verify idempotency with a second dry-run, and add a ->withSkip() for fixtures that only look like tests.

To the team doing the work: Treat the ruleset as an accelerator, not an oracle. It clears the boring majority of mechanical conversions — the 70% — but expect a manual tail around mocking, custom helpers, data providers, dependency ordering, and lifecycle semantics. Dry-run first, commit per module or directory, and review every diff even when tests pass: a green suite is not proof of correctness, because a rewritten test can pass while asserting less. Compare test and coverage counts against the PHPUnit baseline before trusting any transformation, and run a test-count assertion alongside the CI dry-run gate so a rule that deletes a test doesn't pass silently. Retire the plugin or disable the set once migration is complete — leaving an unmaintained codemod enabled in CI is a future upgrade tripwire for zero benefit.