Pest PHP Testing Framework Migration: A Comprehensive Guide

Mar 15, 2026

In 2004, Sebastian Bergmann released PHPUnit, creating the de facto standard for PHP testing that would persist for nearly two decades. The object-oriented, class-based approach—where tests extend TestCase—became deeply familiar to generations of PHP developers. Testing frameworks, though, evolve as our expectations change.

By 2019, Nuno Maduro observed that writing tests could feel more like describing behavior than constructing boilerplate. This observation led to Pest, a framework built on top of PHPUnit that preserves all of PHPUnit’s capabilities while offering a different ergonomics approach—one that emphasizes readability and developer experience.

When considering migration, the question isn’t which framework is objectively better. Rather: does Pest’s functional style offer tangible benefits for your team’s workflow, and can you manage the transition without disrupting your project’s stability?

In this guide, we’ll walk through the migration process step by step. We’ll start by comparing the two frameworks to understand their philosophies, then prepare your test suite, convert tests systematically, and verify your migration succeeds. By the end, you’ll have a clear roadmap for bringing Pest into your PHP projects.

Understanding the Testing Framework Landscape

PHPUnit has been the cornerstone of PHP testing for nearly two decades—it’s mature, stable, and supported by an extensive ecosystem. For many teams, PHPUnit continues to serve admirably. There’s no pressing need to switch if your current setup works well.

Of course, testing frameworks evolve as our expectations change. Pest emerged from the observation that writing tests could feel more like describing behavior than constructing boilerplate. Built on top of PHPUnit, Pest preserves all of PHPUnit’s capabilities—though it offers a different ergonomics approach—one that emphasizes readability and developer experience.

PHPUnit: The Proven Standard

PHPUnit follows an object-oriented approach where tests extend TestCase classes. This pattern is familiar to many PHP developers and integrates well with IDE features like autocomplete. The framework has been battle-tested in countless production applications, and its maturity means you’ll find extensive documentation and community knowledge. Sebastian Bergmann created PHPUnit in 2004, and it has been the de facto standard ever since.

Pest: A Modern Approach

Pest takes a functional approach, using plain PHP functions rather than requiring class inheritance. Tests read like sentences: test('it can calculate total', function () { ... }). This style can make tests more approachable for developers who prefer simpler syntax. The framework also provides an elegant test runner with clear output formatting. Pest was first released in 2019 by Nuno Maduro and has gained popularity for its developer-friendly design.

Trade-offs to Consider

Before committing to migration, we should acknowledge the trade-offs:

Learning curve: Pest requires learning new patterns like test(), expect(), and uses(). While simple, this is an extra investment.
Ecosystem differences: PHPUnit’s extensions and integrations may not have direct Pest equivalents—though Pest can use most PHPUnit code directly.
Team familiarity: If your team already knows PHPUnit well, the productivity gain from Pest may be marginal.
Migration effort: Converting an existing test suite takes time—time that could be spent on features or bug fixes.
Philosophical fit: Some teams prefer the structure of classes; others find Pest’s functional style more natural.

We recommend migration only if you see a clear benefit—improved test readability, faster test writing, or better developer experience for your team. If PHPUnit meets your needs, there’s no shame in staying with it.

Deciding Whether to Migrate

One may wonder: how do I know if Pest is right for my project? The answer, of course, depends on your context. Consider Pest if:

Your team finds PHPUnit tests verbose or cumbersome
You’re starting a new project and want a fresh approach
You value test readability as a priority
Your test suite is relatively small to medium sized
You have bandwidth for the migration effort

Stick with PHPUnit if:

Your current tests are working well and your team is comfortable
You have a very large test suite (migration becomes significant)
You rely heavily on PHPUnit-specific extensions that lack Pest integration
You need maximum IDE support for test navigation

In the following sections, we’ll assume you’ve decided to proceed and show you how to migrate effectively.

Prerequisites

Before we begin the migration, we need to ensure your environment meets the requirements and your test suite is ready.

System Requirements

Pest requires PHP 8.0 or higher. PHPUnit also requires at least PHP 7.3—though since Pest builds on PHPUnit, we’ll need PHP 8.0+ when using Pest. We should confirm your development environment meets this requirement:

$ php -v
PHP 8.1.10 (cli) (built: Sep 5 2023 15:30:42)

If you’re on an older PHP version, we recommend upgrading before attempting migration—though this presents a good opportunity to modernize your stack.

You’ll also need Composer, the PHP package manager. If you don’t have it installed, follow the installation instructions at https://getcomposer.org/download/. Verify with:

$ composer --version
Composer version 2.5.5 2023-07-12 14:35:22

Test Suite Requirements

All tests passing: Before migrating, ensure your entire PHPUnit test suite passes without failures. A clean baseline is crucial—we need to distinguish between pre-existing issues and migration-introduced problems.
Understand custom helpers: Take note of any custom base test classes, helper traits, or global functions your tests rely on. These may need adaptation for Pest.
Version control: Your project should be under Git (or another VCS) with all changes committed. Migration involves many file modifications; being able to roll back is essential.

Tooling

We’ll use the following tools during migration:

Composer: To install Pest as a dependency
Pest executable: ./vendor/bin/pest for running tests
Your existing PHPUnit configuration: Typically phpunit.xml or phpunit.xml.dist

One may wonder: do I need to uninstall PHPUnit? Not necessarily—Pest works alongside PHPUnit, and you can keep both during a gradual migration. Of course, we’ll remove PHPUnit as a standalone dev dependency once migration is complete—but we’ll cover that later.

Step-by-Step Migration Guide

Migrating from PHPUnit to Pest is a straightforward process. Here’s a step-by-step guide to get you started.

1. Install Pest

We’ll start by installing Pest as a development dependency. We recommend using the --with-all-dependencies flag to ensure Composer updates PHPUnit and related packages to compatible versions automatically:

$ composer require pestphp/pest --dev --with-all-dependencies
Using version ^2.5 for pestphp/pest
./composer.json has been updated
Running Composer update pestphp/pest
...
Package pestphp/pest installed successfully

Of course, you can also install Pest globally with composer global require pestphp/pest if you prefer a system-wide installation—but the project-local approach we show here is more common and ensures version consistency per project.

Next, we’ll create the tests/Pest.php bootstrap file. This file configures Pest’s behavior—for example, which base test classes to use and where to look for tests. You can generate this automatically by running:

$ ./vendor/bin/pest --init

This creates a default tests/Pest.php with commented placeholders. Let’s examine a typical setup, especially the uses() calls that bind custom base classes:

<?php

use Tests\TestCase;

/*
|--------------------------------------------------------------------------
| Test Case
|--------------------------------------------------------------------------
|
| The closure you provide to your test functions is always bound to a specific PHPUnit test
| case class. By default, that class is "PHPUnit\Framework\TestCase". Of course, you may
| need to change it using the "uses()" function to bind a different classes or traits.
|
*/

uses(TestCase::class)->in('Feature');
uses(TestCase::class)->in('Unit');

/*
|--------------------------------------------------------------------------
| Expectations
|--------------------------------------------------------------------------
|
| When you're writing tests, you often need to check that values meet certain conditions. The
| "expect()" function gives you access to a set of expectations that you can use to check
| values against various conditions.
|
*/

/*
|--------------------------------------------------------------------------
| Functions
|--------------------------------------------------------------------------
|
| Pest provides a lot of functionality out of the box—but you may have project-specific
| testing code that you'd like to reuse across tests. In this section, you can define global
| helper functions to reduce repetition in your test files.
|
*/

// Example: a custom helper function
// function customHelper()
// {
//     // ...
// }

Note that the generated file includes commented examples. You’ll want to uncomment and adjust the uses() statements to match your project’s test structure. If you have a custom Tests\TestCase class used by your Feature tests, bind it as shown. This step is crucial—without it, your tests may fail because they can’t access your custom setup logic.

Let’s check what a typical project structure looks like after initialization:

tests/
├── Unit/
│   └── ExampleTest.php
├── Feature/
│   └── ExampleTest.php
├── Pest.php
└── CreatesApplication.php (optional, for Laravel)

The uses(TestCase::class)->in('Feature') line tells Pest to bind your custom Tests\TestCase to all tests in the Feature directory. Without this binding, tests that rely on your custom setup (like database connections or service providers) will fail.

Migration Strategy: Gradual vs Full

Before we dive into converting individual tests, let’s consider the overall strategy. There are two main approaches to migrating from PHPUnit to Pest: gradual and full.

Gradual migration means converting tests file by file over time. You keep both PHPUnit and Pest tests coexisting in the same codebase. This approach has several advantages:

Lower risk: If something goes wrong, you can pause migration and continue with PHPUnit.
Incremental effort: Team members can convert tests as they work on related features.
Flexibility: You can stop at any point if the benefits aren’t clear.

The main disadvantage is maintaining two different testing styles temporarily. Your CI configuration may need to run both Pest and PHPUnit, and developers must be comfortable with both syntaxes.

Full migration means converting all tests in one go—often done over a dedicated sprint or focused effort. Benefits include:

Unified codebase: All tests follow the same patterns.
Simpler CI: Only need one test runner.
Immediate productivity gain: Entire team uses Pest from day one.

Drawbacks include larger upfront time investment and higher risk if issues arise en masse.

Which approach should you choose? The decision depends on your context:

For small to medium test suites (a few hundred tests or less), a full migration over a week or two is often feasible.
For large legacy suites, gradual migration is safer—start with new tests in Pest and migrate old ones as you touch those files.
If your team is new to Pest, consider a trial conversion of a small module first—this gives you a feel for the effort involved.

In this guide, we’ll present conversion techniques that work for either approach. You can apply them one file at a time or batch process many files at once.

2. Converting a PHPUnit Test to Pest

Let’s take a typical PHPUnit test and convert it to Pest.

PHPUnit Example:

<?php

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;
use App\Models\User;

class UserTest extends TestCase
{
    /** @test */
    public function it_can_get_the_users_full_name()
    {
        $user = new User([
            'first_name' => 'John',
            'last_name' => 'Doe',
        ]);

        $this->assertEquals('John Doe', $user->full_name);
    }
}

Pest Equivalent:

<?php

use App\Models\User;

test('it can get the users full name', function () {
    $user = new User([
        'first_name' => 'John',
        'last_name' => 'Doe',
    ]);

    expect($user->full_name)->toBe('John Doe');
});

As you can see, the Pest version is more concise and readable. The test() function replaces the class-based structure of PHPUnit, and the expect() function provides a more fluent way to write assertions.

3. Handling Setup and Teardown

PHPUnit’s setUp() and tearDown() methods can be replaced with Pest’s beforeEach() and afterEach() functions.

PHPUnit setUp():

class UserTest extends TestCase
{
    protected $user;

    protected function setUp(): void
    {
        parent::setUp();
        $this->user = new User(['first_name' => 'John']);
    }

    // ...
}

Pest beforeEach():

beforeEach(function () {
    $this->user = new User(['first_name' => 'John']);
});

test('it has a first name', function () {
    expect($this->user->first_name)->toBe('John');
});

4. Datasets

Pest’s datasets are a powerful feature that can help you reduce code duplication.

PHPUnit dataProvider:

/**
 * @test
 * @dataProvider invalidEmails
 */
public function it_validates_emails($email)
{
    // ...
}

public function invalidEmails()
{
    return [
        ['invalid-email'],
        ['invalid@email'],
    ];
}

Pest with():

test('it validates emails', function ($email) {
    // ...
})->with([
    'invalid-email',
    'invalid@email',
]);

Verification and Testing

After converting tests (or during gradual migration), it’s essential to verify that your test suite behaves correctly. In this section, we’ll cover running tests with Pest, interpreting results, measuring coverage, and integrating with CI.

Running Tests with Pest

Pest provides a straightforward command-line interface. The simplest invocation runs all tests in your tests directory:

$ ./vendor/bin/pest

Pest automatically detects both Pest-style tests (functions) and classic PHPUnit test classes—so you can run the entire suite during gradual migration. If you want to run only a specific file or directory:

$ ./vendor/bin/pest tests/Feature
$ ./vendor/bin/pest tests/Unit/UserTest.php

You can also filter by test name using the --filter option:

$ ./vendor/bin/pest --filter "it can get the users full name"

Understanding Pest Output

Pest’s default output is concise and color-coded:

  21 Tests (21) Passed in 0.34 seconds. Memory: 10.00 MB

Each dot (.) represents a passing test; failures are shown with an F. If a test fails, Pest prints a detailed error with stack trace:

  1) Tests\Feature\PaymentTest@it processes refunds
     Expectation failed for ... (Failed asserting ...

You can enable more verbose output with --verbose or the -v flag:

$ ./vendor/bin/pest -v

This prints the name of each test as it runs.

For teams migrating from PHPUnit, Pest also supports the --testdox format, which provides a narrative description:

$ ./vendor/bin/pest --testdox

Output:

Payment
 - it processes refunds
 - it handles declined payments
User
 - it can get the users full name
 - it validates email addresses

This format may feel more familiar and is useful for generating documentation.

Code Coverage

Pest uses PHPUnit’s code coverage driver under the hood. To generate a coverage report, you’ll need Xdebug or PCOV installed. Once configured, run:

$ ./vendor/bin/pest --coverage

This produces an HTML coverage report in the coverage/ directory by default. You can also specify formats:

$ ./vendor/bin/pest --coverage-html coverage/
$ ./vendor/bin/pest --coverage-clover clover.xml

Coverage helps identify untested code—especially useful after migration to ensure you haven’t lost coverage.

Parallel Execution and Caching

For large test suites, Pest can run tests in parallel to reduce execution time:

$ ./vendor/bin/pest --parallel

By default, Pest uses the number of available CPU cores. You can control processes with --processes:

$ ./vendor/bin/pest --parallel --processes=4

Pest also offers built-in caching to speed up subsequent runs. The first run caches which tests need to execute based on file changes:

$ ./vendor/bin/pest --cache

The cache is stored in .pest.cache by default. Use --no-cache to bypass.

CI/CD Integration

Pest works well in continuous integration pipelines. Here’s a typical GitHub Actions configuration:

name: Tests
on: [push, pull_request]
jobs:
  pest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          extensions: mbstring, pdo_sqlite
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      - name: Run tests
        run: ./vendor/bin/pest --coverage --coverage-clover=clover.xml
      - name: Upload coverage
        uses: actions/upload-artifact@v3
        with:
          name: coverage-report
          path: clover.xml

If you’re still running a mixed test suite (both PHPUnit and Pest), you can call Pest—it will handle both.

Verifying Migration Success

How do you know migration is complete and successful? We recommend:

All tests passing: Run ./vendor/bin/pest and confirm no failures.
No PHPUnit-only tests remain: Check that all test files use Pest’s test() function or have been converted. You can search for extends TestCase to find remaining PHPUnit classes.
Coverage unchanged or improved: Compare coverage reports before and after migration to ensure you haven’t inadvertently excluded tests.
CI passes: Confirm your CI pipeline runs Pest without issues.
Team comfortable: Ensure developers understand how to write and run Pest tests. A short knowledge-sharing session can help.

Once these criteria are met, you may choose to remove the standalone phpunit/phpunit dependency from your composer.json. Pest already includes PHPUnit as a dependency, so you no longer need it explicitly.

Note: If you’re using PHPUnit-specific extensions or integrations, check for Pest compatibility before removing PHPUnit. Some tools might still require the explicit dependency.

Troubleshooting and Common Issues

Migration doesn’t always go smoothly. We’ve encountered these common issues—and their solutions—in real projects.

Pest doesn’t recognize my existing PHPUnit tests

Problem: When running ./vendor/bin/pest, only Pest tests execute; PHPUnit tests are skipped.

Cause: Pest automatically detects tests based on naming conventions. By default, it looks for files ending in Test.php. If your PHPUnit tests follow a different pattern (e.g., *Test.php vs *_test.php), Pest may not detect them.

Solution: Configure Pest to recognize your existing test file pattern. Create or modify pest.php in your project root:

// pest.php
return [
    'test_paths' => [
        'tests/Unit',
        'tests/Feature',
    ],
];

Alternatively, ensure your PHPUnit tests follow Pest’s conventions: files should be named SomethingTest.php and located in your tests directory.

Tests fail after migration with “Class ‘TestCase’ not found”

Problem: Converting tests results in errors about missing TestCase class.

Cause: Pest tests don’t automatically extend PHPUnit\Framework\TestCase. If your original tests relied on a custom base class (e.g., Tests\TestCase), you need to explicitly bind it using Pest’s uses() function.

Solution: In your tests/Pest.php file, add:

use Tests\TestCase;

uses(TestCase::class)->in('Unit');

This tells Pest to bind your custom TestCase to tests in the Unit directory. Adjust the namespace and path as needed.

Custom helper functions are undefined

Problem: After converting tests, global helper functions (like factory() or actingAs()) are no longer available.

Cause: Pest doesn’t automatically load your existing test helper files. PHPUnit commonly loads bootstrap files via phpunit.xml.

Solution: You have two options. First, you can tell Pest to bootstrap your existing PHPUnit configuration by creating a pest.php file that loads the PHPUnit bootstrap:

// pest.php
use PHPUnit\Framework\TestCase;

require_once __DIR__.'/vendor/autoload.php'; // adjust path as needed

Better yet—Pest can automatically use your PHPUnit bootstrap if you have a phpunit.xml file. Just make sure the bootstrap attribute in phpunit.xml points to the correct file. Pest will respect that configuration.

If your helpers are defined as functions in a file like tests/helpers.php, ensure they are required in your bootstrap. That’s typically the same approach you’d use for PHPUnit.

Dataset methods not working in Pest

Problem: Converting @dataProvider to Pest’s with() doesn’t work as expected.

Cause: Datasets in Pest work differently. The with() method expects an array of values, but your data provider may have returned arrays structured differently, or you may be referencing a separate method incorrectly.

Solution: Pest datasets are inline. Convert your data provider:

PHPUnit:

/** @test @dataProvider nameProvider */
public function test_name($first, $last) { ... }

public function nameProvider() {
    return [['John', 'Doe'], ['Jane', 'Smith']];
}

Pest:

test('it handles names', function ($first, $last) {
    // ...
})->with([
    ['John', 'Doe'],
    ['Jane', 'Smith'],
]);

If your data provider contains many entries, you can also define a separate dataset function and reference it:

test('it handles names', function ($first, $last) {
    // ...
})->with(buildNameDataset());

function buildNameDataset() {
    return [
        ['John', 'Doe'],
        ['Jane', 'Smith'],
    ];
}

Pest test runner output looks different than expected

Problem: You’re used to PHPUnit’s verbose output and find Pest’s output confusing.

Cause: Pest’s test runner has a different default presentation. It uses a simpler, color-coded output that some find less detailed.

Solution: Pest offers various output formats and options. For a more PHPUnit-like experience, try running with the --verbose flag:

$ ./vendor/bin/pest --verbose

You can also specify the format:

$ ./vendor/bin/pest --display=testdox

The testdox format provides a human-readable description of each test as it runs, similar to PHPUnit’s --testdox option.

CI/CD integration fails after adding Pest

Problem: Your CI pipeline breaks after adding Pest as a dependency.

Cause: Pest requires the Pest binary to be executed, but your CI may still be calling phpunit. Also, Pest’s version constraints might conflict with other dependencies.

Solution: Update your CI configuration to run Pest explicitly:

# .gitlab-ci.yml or GitHub Actions
- name: Run tests
  run: ./vendor/bin/pest

If you want to keep both Pest and PHPUnit tests during a gradual migration, you can call Pest—it will run both types. Once all tests are converted to Pest syntax, you can remove the standalone phpunit dependency from composer.json.

Be sure to pin Pest to a specific version that matches your team’s testing strategy. Use composer require pestphp/pest:^2.0 to avoid unexpected upgrades.

”Class ‘expect’ not found” errors

Problem: Pest tests throw “Class ‘expect’ not found” when using expect().

Cause: The expect() function is a global function provided by Pest. If it’s not recognized, Pest might not be properly bootstrapped or the autoloader isn’t loaded.

Solution: Ensure you have a proper tests/Pest.php file that includes the necessary expect() function. The default stub from ./vendor/bin/pest --init sets this up. If you’re missing it, run:

$ ./vendor/bin/pest --init

This generates a default tests/Pest.php with the necessary setup.

Also, confirm that Composer’s autoloader is included in your bootstrap. Typically, tests/Pest.php will have something like:

// tests/Pest.php
use function Pest\Laravel\... // optional, depending on your framework
// ...

If you’re still having issues, check that you’re running tests through Pest (./vendor/bin/pest) rather than directly via php.

Migration introduces subtle test failures

Problem: After converting tests, some tests pass in PHPUnit but fail in Pest.

Cause: Although Pest is built on PHPUnit, subtle differences in setup and bootstrapping can alter the test environment. For instance, Pest may not load the same bootstrap files or initialize the framework in the same order.

Solution: Compare your PHPUnit bootstrap (phpunit.xml’s bootstrap attribute) with your Pest bootstrap (tests/Pest.php). Ensure both load the same application initialization (e.g., Laravel’s createApplication() or Symfony’s kernel). You may need to manually call the same bootstrap routine in tests/Pest.php.

One common pitfall: if your tests rely on setUp() methods from a custom TestCase class, make sure that class is bound via uses() as described earlier. Without that binding, Pest won’t execute your setUp logic—leading to missing database connections, configurations, or other setup.

If failures persist, run a side-by-side comparison: pick a failing test, run it with PHPUnit and Pest, and examine the differences in environment (e.g., $_ENV, loaded configurations). Use debugging output like dd() or var_dump to inspect state.

Composer dependency conflicts

Problem: Running composer require pestphp/pest results in dependency conflicts.

Cause: Pest requires specific versions of its dependencies (including PHPUnit itself). Your project’s existing composer.json constraints might conflict.

Solution: Use the --with-all-dependencies flag (as shown earlier) to allow Composer to update related packages:

$ composer require pestphp/pest --dev --with-all-dependencies

This updates PHPUnit and other dev dependencies to versions compatible with Pest. If conflicts still occur, you may need to manually adjust version constraints in composer.json. Check the Pest documentation for the minimum supported versions of PHPUnit and other packages.

Of course, dependency conflicts sometimes indicate that your project uses an older PHP version that cannot be upgraded. In that case, Pest may not be compatible. Consider upgrading PHP first, or continue using PHPUnit until you can modernize the stack.

Performance regression after migration

Problem: Tests run slower with Pest than they did with PHPUnit.

Cause: Pest’s test runner has different internal caching and parallelization strategies. If you were using PHPUnit’s caching or parallel test runners (e.g., paratest), those may not be configured the same way in Pest.

Solution: Pest supports parallel test execution out of the box via the --parallel flag:

$ ./vendor/bin/pest --parallel

This can actually improve performance significantly. Also, ensure you’re using Pest’s built-in caching mechanism:

$ ./vendor/bin/pest --cache

Run ./vendor/bin/pest --help to see all options.

If performance remains an issue, profile your tests to identify slow areas—maybe database seeding or external service calls. Those aren’t Pest-specific, but the migration might have exposed them.

Legacy PHPUnit test syntax not recognized

Problem: Older PHPUnit tests using annotations like @test or @group aren’t being recognized by Pest.

Cause: Pest expects tests to be defined using the test() function or methods prefixed with test. While Pest supports some PHPUnit annotations via compatibility layers, not all are automatically translated.

Solution: Ensure your tests are either in files that Pest can scan for PHPUnit-style test classes (Pest automatically detects classes extending TestCase), or better yet, convert them to Pest syntax. For a gradual migration, you can keep some tests as PHPUnit classes and others as Pest functions—Pest runs both. However, annotations like @depends might not work seamlessly; test dependencies should be rewritten using Pest’s higher-order tests or explicit ordering.

If you need to preserve a large legacy test suite without converting, you might consider keeping PHPUnit as the primary runner and only writing new tests in Pest. That’s a valid approach.

Conclusion

Migrating from PHPUnit to Pest can significantly improve your testing workflow, making your tests more readable, maintainable, and enjoyable to write. By following this guide, you can start leveraging the power of Pest in your PHP projects today. Happy testing!