laravel-pest-rector

Files (2)

• SKILL.md
• generated-config-trap.md · references/

SKILL.md (first lines)

# Pest Rector — refactor tests into Pest matchers

Turns raw assertions into Pest's own matchers across an existing Pest 5 suite:

```diff
-expect(count($array))->toBe(5);
-expect(array_key_exists('id', $array))->toBeTrue();
+expect($array)->toHaveCount(5)
+    ->toHaveKey('id');
```

60 rules, one set. It refactors tests that are **already Pest** — it does not convert PHPUnit
class-style tests (that is `/laravel-pest5-upgrade` step 3, and a hard prerequisite here).

Despite the name, nothing in this flow is Laravel-specific — it works on any Pest 5 PHP project.
The prefix keeps it beside its sibling skill.

## 1. Preconditions — both are hard gates

**Pest 5 installed.** `vendor/bin/pest --version` reports 5.x. Not there yet ⇒ `/laravel-pest5-upgrade` first.

**A green suite, unfiltered.** This rewrites hundreds of test files at once; without a known-good
baseline you cannot attribute a single failure afterwards.

```bash
./vendor/bin/pest --parallel --no-tia
```

`--no-tia` matters even here. If the repo followed `/laravel-pest5-upgrade`, `pest()->tia()->locally()`
makes a bare `--parallel` run impact-filtered — a green that proves nothing about the files Rector
is about to touch. **Every suite run in this skill is `--no-tia`.**

Working tree clean before step 4 — Rector rewrites in place with no backup, and a dirty tree makes
its diff unreviewable.

## 2. Install

```bash
composer require pestphp/pest-plugin-rector --dev
composer require rector/rector --dev
```

The plugin already depends on `rector/rector ^2.6.1`, so `vendor/bin/rector` arrives either way.
The second line is what the docs prescribe and it pins Rector at top level — worth having when the
plugin's own constraint later widens.

**Require v5.0.2 or newer.** v5.0.0–v5.0.1 shipped a `ChainExpectCallsRector` bug that collapsed
two `expect()` calls on an AST-equal *side-effectful* subject into a single chain, silently dropping
the second evaluation and turning passing tests red. Fixed in v5.0.2 by an `isSideEffectFree()`
guard. `composer require` takes the latest by default — confirm with
`composer show pestphp/pest-plugin-rector`.

Not this plugin's job: converting PHPUnit class-style tests to Pest. That is
`pestphp/pest-plugin-drift`, a separate package — and `/laravel-pest5-upgrade` step 3.

## 3. Write `rector.php` BEFORE invoking rector at all

⛔ **This is the step that decides whether the skill did anything at all.**

With no `rector.php` present, `vendor/bin/rector` asks *"No rector.php config found. Should we
generate it for you?"* — and **you do not get to decline it.** Symfony's question helper returns
the default answer when stdin is not a TTY, and an agent shell is not a TTY, so the prompt
auto-answers **yes**, writes the file, and exits SUCCESS *having processed nothing*. Every later
run then silently uses that generated config.

So the config has to exist before rector is invoked even once. There is no `rector init` to reach
for — the command does not exist in Rector 2.x. Write the file.

The generated one carries the project's whole source tree and **no Pest set**, so a `process`
against it applies generic Rector rules to your application while performing zero Pest refactoring.

Write this instead:

```php
<?php

declare(strict_types=1);

use Pest\Rector\Set\PestSetList;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/tests'])
    ->withSets([
        PestSetList::CODING_STYLE,
    ]);
```

Two things are load-bearing: `withPaths` names **only** `tests/`, and `withSets` registers
`PestSetList::CODING_STYLE`. Drop either and this becomes a generic refactor of unrelated code.

**A `rector.php` already exists?** Do not overwrite it — merge. Add `PestSetList::CODING_STYLE` to
its `withSets(...)`, and if its `withPaths(...)` reaches beyond `tests/`, stop and ask: this skill's
gates assume a test-only blast radius, and the existing config is someone's deliberate choice.

Measured cost of getting this wrong: `references/generated-config-trap.md`.

## 4. Preview, read the diff, then apply

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

**Read it before applying** — this is the review, and there is no other. Confirm three things:
every path is under `tests/`; the changes are Pest matcher conversions and expectation chaining;
the file count is in the range you expect for the suite's size.

**`--dry-run` exits non-zero when it finds changes** (`ExitCode::CHANGED_CODE`). Here that is the
success case, not a failure — never gate on `$?` alone at this step, and never let a wrapper read
it as an error and abort.

The preview is faithful. Rector re-runs the whole rule pipeline over each file until an iteration
changes nothing, and `--dry-run` uses that same loop, returning just before the write — so chained
effects, like a matcher rewrite that then enables a chain merge, are already in the diff. Only a
cross-file cascade could need a second pass, which is what step 5's final check catches.

**`->only()` markers get stripped.** `RemoveOnlyRector` is in the set, so any focused test left in
the working tree loses its `->only()`. Look for that in the dry-run diff before applying.

From bravros/bravros, MIT.

More from bravros/bravros