What's new in Pest 3 and how to upgrade

Introduction to Pest 3

Pest, my favorite PHP testing framework, has released version 3. It was presented at Laracon US 2024 by Nuno Maduro, and I could not wait to dive in. In this post, I cover what’s new in Pest 3 and how to upgrade from Pest 2 to Pest 3, with tips for PHPUnit 11 and Laravel testing.

Is Pest 3 the easiest upgrade ever?

Upgrading to Pest PHP 3 is simple, but use the stable release. Pest 3 requires PHP 8.2 or higher. Update your composer.json, bump any official Pest plugins to ^3.0, and then run a composer update. Full details are in the Upgrade Guide.

{
  "require-dev": {
    "pestphp/pest": "^3.0"
  }
}

Then run:

composer update

Notes:

Pest 3 is built on PHPUnit 11, which may change how some suites behave. Review the Upgrade Guide before updating.
If you use Laravel, make sure Collision is on v8: nunomaduro/collision:^8.0.
Use ./vendor/bin/pest to run your tests unless you have a global install.

What’s new in Pest 3?

Architecture testing presets

One standout feature is Architecture Testing Presets. These help you enforce rules and best practices without writing everything by hand. Confirmed presets are:

php
security
laravel
strict
relaxed

Use them like this:

arch()->preset()->laravel();

And here’s how you can use the other presets:

arch()->preset()->php();
arch()->preset()->security();
arch()->preset()->strict();
arch()->preset()->relaxed();

Need exceptions? Skip specific files or namespaces with ignoring():

arch()->preset()->laravel()->ignoring('App\\Models\\Scopes');

// or with a class constant
arch()->preset()->laravel()->ignoring(App\Models\Scopes::class);

I wrote more about this in my guide to architecture testing presets in Pest 3. For an overview of presets and ignoring(), see the Pest 3 announcement.

Mutation testing: how reliable are your tests?

Mutation testing makes small changes (mutations) to your code and checks if your tests catch them. It is a great way to measure test quality.

Install the plugin:

composer require pestphp/pest-plugin-mutate --dev

Run mutation tests:

./vendor/bin/pest --mutate

Tip: add --parallel to speed things up on larger suites.

Pest’s mutation tests in action.

As you can see, this is a disaster. But in my defense, it is a new project and a work in progress!

Read more in the Mutation Testing docs and the Pest Mutate plugin repository.

Team Management

Team Management lets you track todos, notes, assignees, issues, and pull requests right from your tests and the CLI. To link to GitHub, first configure your project in tests/Pest.php:

pest()->project()->github('org/repo');

Now you can mark work as todo or done, and attach context:

test('something happens when…', function () {
    // …
})->todo(
    assignee: 'benjamincrozat',
    issue: 42,
    note: 'Focus on optimizing the user lookup query.'
);

test('an event is triggered when…', function () {
    // …
})->done()->pr(101);

You can also link on groups:

describe('auth', function () {
    // …
})->issue(13);

CLI filters make it easy to focus your run:

./vendor/bin/pest --todos
./vendor/bin/pest --notes
./vendor/bin/pest --assignee=benjamincrozat
./vendor/bin/pest --issue=11
./vendor/bin/pest --pr=1

See the Team Management docs and the Pest CLI reference.

Nested describes

Pest 3 lets you nest describe groups to organize related tests and share hooks more clearly.

describe('API', function () {
    describe('Auth', function () {
        test('logs in', function () {
            // …
        });
    });
});

Learn more in the Pest 3 announcement.

New configuration API

There is a new, fluent configuration API in tests/Pest.php so you can define project-level settings and integrations (like GitHub) in one place using pest() helpers. See the Pest 3 announcement for examples.

Conclusion

Pest 3 brings five big wins: architecture testing presets, Mutation Testing, Team Management, nested describes, and a new configuration API. Upgrading is straightforward: require pestphp/pest:^3.0, ensure PHP 8.2+, update plugins to ^3.0, and run composer update. Because Pest 3 is built on PHPUnit 11, review the official Upgrade Guide and refer to the docs for Team Management, Mutation Testing, and the Pest 3 announcement. Now run ./vendor/bin/pest and enjoy faster, clearer Laravel testing with Pest PHP 3.

Did you like this article? Then, keep learning: