Upgrading To 3.x From 2.x
Estimated Upgrade Time: 2 minutes
We make an effort to document every potential breaking change, but some of these changes may exist in less frequently used sections of the framework. As a result, only a subset of these changes may impact your application.
Updating Dependencies
Likelihood Of Impact: High
Pest 3 now requires PHP 8.2.0 or greater. To start migrating from Pest 2 to Pest 3, update the pestphp/pest
dependency to ^3.0
in your application's composer.json
file.
1- "pestphp/pest": "^2.0",2+ "pestphp/pest": "^3.0",
In addition, if you are using Laravel, please upgrade Collision to version 8. Note that, Laravel 11 is required.
1- "nunomaduro/collision": "^7.0",2+ "nunomaduro/collision": "^8.0",
All other Pest maintained plugins should be updated to version ^3.0
in your application's composer.json
file.
1- "pestphp/pest-plugin-laravel": "^2.0",2+ "pestphp/pest-plugin-laravel": "^3.0",
PHPUnit 11 Changes
Likelihood Of Impact: Medium
Pest 3 is built on top of PHPUnit 11. This means that any notable changes made to PHPUnit 11 might have an impact on your test suite. To examine all the changes introduced in PHPUnit 11, please consult the PHPUnit 11 changelog.
toHaveMethod
and toHaveMethods
Expectations
Likelihood Of Impact: Low
The toHaveMethod
and toHaveMethods
expectations were replaced by the toHaveMethod
and toHaveMethods
architectural expectations. If you were using these expectations, you can no longer provide a object as architectural expectations expect an namespace or a class name.
1-expect($object)->toHaveMethod('method');2+expect($object::class)->toHaveMethod('method');
pest()
Pest 2 Deprecations
During Pest 2 release, some features were deprecated and are now removed in Pest 3. Here are the changes you should be aware of:
tap()
Method
Likelihood Of Impact: Low
When performing high order testing, you might have utilized the tap()
method to invoke assertions on an object that needs lazy evaluation during runtime. With Pest 2, the tap()
method is deprecated, and on Pest 3 it was removed. Instead, you should use the defer()
method.
1it('creates admins')2- ->tap(fn () => $this->artisan('user:create --admin'))3+ ->defer(fn () => $this->artisan('user:create --admin'))4 ->assertDatabaseHas('users', ['id' => 1]);
Upgrading To 2.x From 1.x
Estimated Upgrade Time: 2 minutes
We make an effort to document every potential breaking change, but some of these changes may exist in less frequently used sections of the framework. As a result, only a subset of these changes may impact your application.
Updating Dependencies
Likelihood Of Impact: High
Pest 2 now requires PHP 8.1.0 or greater. To start migrating from Pest 1 to Pest 2, update the pestphp/pest
dependency to ^2.0
in your application's composer.json
file.
1- "pestphp/pest": "^1.22",2+ "pestphp/pest": "^2.0",
Next, you can remove PHPUnit from your list of dependencies if it is included.
1- "phpunit/phpunit": "^9.5.10",
In addition, if you are using Laravel, please upgrade Collision to version 7. Note that, Laravel 10 is required.
1- "nunomaduro/collision": "^6.0",2+ "nunomaduro/collision": "^7.0",
If you are using the Parallel Plugin (or Paratest), you may remove it from your dependencies since it is now included with Pest by default.
1- "brianium/paratest": "^6.8.1",2- "pestphp/pest-plugin-parallel": "^1.2.1",
The Global Assertions Plugin is archived and should be removed from your dependencies.
1- "pestphp/pest-plugin-global-assertions": "^1.0.0",
If you relied on the Global Assertions Plugin, you may access the same underlying assertions using the $this
variable. Alternatively, you may migrate to the Expectation API.
1test('sum', function () {2 $result = sum(1, 2);3 4- assertSame(3, $result);5+ $this->assertSame(3, $result); // or expect($result)->toBe(3)6});
All other Pest maintained plugins should be updated to version ^2.0
in your application's composer.json
file.
1- "pestphp/pest-plugin-laravel": "^1.4",2+ "pestphp/pest-plugin-laravel": "^2.0",
If you are using the Faker Plugin, the faker()
function has been renamed to fake()
. You will need to update all uses.
1- use function Pest\Faker\faker;2+ use function Pest\Faker\fake;3 4test('faker', function () {5- expect(faker()->name())->toBeString();6+ expect(fake()->name())->toBeString();7});
PHPUnit 10 Changes
Likelihood Of Impact: Medium
If you were previously using PHPUnit instead of Pest, it's possible that your phpunit.xml
file needs to be updated. When this is the case, you may encounter the following message when running Pest 2 for the first time.
1WARN Your XML configuration validates against a deprecated schema. Migrate your XML configuration using "--migrate-configuration"!
To address this issue, simply re-run Pest with the --migrate-configuration
option.
1./vendor/bin/pest --migrate-configuration
Pest 2 is built on top of PHPUnit 10. This means that any notable changes made to PHPUnit 10 might have an impact on your test suite. To examine all the changes introduced in PHPUnit 10, please consult the PHPUnit 10 changelog.
High Order Testing
Likelihood Of Impact: Low
When performing high order testing, you might have utilized the tap()
method to invoke assertions on an object that needs lazy evaluation during runtime. With Pest 2, the tap()
method is deprecated. Instead, you should use the defer()
method.
1it('creates admins')2- ->tap(fn () => $this->artisan('user:create --admin'))3+ ->defer(fn () => $this->artisan('user:create --admin'))4 ->assertDatabaseHas('users', ['id' => 1]);
Datasets
Bound Datasets
Likelihood Of Impact: Very low
If you are utilizing "bound" datasets and binding a single dataset argument, you must now type the corresponding test parameter.
1-it('can generate the full name of a user', function ($user, $fullName) {2+it('can generate the full name of a user', function (User $user, $fullName) {3 expect($user->full_name)->toBe($fullName);4})->with([5 [fn() => User::factory()->create(['first_name' => 'Nuno', 'last_name' => 'Maduro']), 'Nuno Maduro'],6 [fn() => User::factory()->create(['first_name' => 'Luke', 'last_name' => 'Downing']), 'Luke Downing'],7 [fn() => User::factory()->create(['first_name' => 'Freek', 'last_name' => 'Van Der Herten']), 'Freek Van Der Herten'],8]);
Scoped Datasets
Likelihood Of Impact: Very low
Although we previously documented in Pest 1 that datasets should only be declared using the dataset
function in the tests/Pest.php
or tests/Datasets.php
files, you could actually declare datasets in any test file within your test suite. However, in Pest 2, with the introduction of scoped datasets, datasets declared in a test file can only be utilized within that same test file. Therefore, if you have a dataset that needs to be accessible globally, please ensure that it is placed in either the tests/Pest.php
or tests/Datasets.php
files.
This concludes the Pest 2 upgrade guide. On the next chapter, we'll cover how can you easily migrate your tests from PHPUnit to Pest: Migrating From PHPUnit