Pest Plugin Mock Laravel Package

Getting Started

Install the plugin via Composer (composer require --dev pestphp/pest-plugin-mock), then enable it in your pest.php config by adding use Pest\Mixins\Mock;. The plugin provides a lightweight, expressive way to create and interact with test doubles—especially for classes where full mocking frameworks like Mockery or PHPUnit are overkill. Your first use case: stubbing a dependency in a unit test for a service class.

use App\Services\PaymentGateway;

test('process payment', function () {
    $gateway = mock(PaymentGateway::class);
    $gateway->shouldReceive('charge')
        ->once()
        ->with(100)
        ->andReturn(true);

    $service = new PaymentService($gateway);
    expect($service->process(100))->toBeTrue();
});

Start by reviewing the plugin’s src/Mocks/Mockable.php and pest.php setup in the repo—despite being archived, it remains compatible with Pest ≥1.0.

Implementation Patterns

• Inline stubbing: Use mock() for quick, inline stubs without creating dedicated mock classes.
• Expectation chaining: Combine shouldReceive(), andReturn(), andThrow(), and with() in fluent chains for clarity.
• Partial mocking: Mock only specific methods of a class (e.g., mock(ClassName::class, ['expensiveMethod'])) to isolate behavior.
• Global helpers: The plugin registers mock(), spy(), and stub() as global helpers—avoid naming conflicts by not importing them explicitly.
• Integration with factory patterns: Pair with factory objects to build realistic test scenarios with minimal boilerplate.

For teams migrating from PHPUnit, replace getMockBuilder() patterns with mock(...)—simpler syntax and same expressive power for 80% of use cases.

Gotchas and Tips

• Archived ≠ deprecated: Though archived, it works with modern Pest versions (tested up to Pest 2.x), but verify compatibility if upgrading Pest major versions.
• Method name escaping: When stubbing methods with special characters (e.g., __invoke()), pass them as strings: ->shouldReceive('__invoke').
• Constraint mismatch: with() accepts matchers (any(), isType('int'), etc.)—avoid raw values if type coercion matters; e.g., with(isType('string')).
• No auto-wiring: Unlike Laravel’s container mocking, mock() does not resolve dependencies—pass collaborators explicitly.
• Reset expectations: If reusing a mock across assertions, call $mock->shouldHaveReceived() before assertions fail, or expectations are lost. Consider spy() for post-hoc verification.
• Debugging tip: Enable Pest\Mixins\Mock::setVerbose(true); in pest.php to log expectations to console (useful for flaky tests).
• Extension point: The plugin is intentionally minimal; for advanced behaviors (e.g., callbacks, async), fall back to Mockery or build your own extension.