Mocking

Why use mocks

When writing tests, there are operations you don’t actually want to run: sending mail, reading and writing to the cache, calling external APIs, and so on. Replacing these operations with a “fake that pretends to be the real thing” is called mocking. The benefits of using mocks include:

Fast tests — Tests finish quickly because external services and heavy operations aren’t executed
Stable tests — Tests always produce the same results, unaffected by the state of external services
Clear test scope — You can verify a single class or method in isolation

Laravel provides helpers that let you mock events, jobs, facades, and more out of the box. Internally it uses Mockery, which you can use without complex setup.

Mocking objects

To mock an object that is injected via the service container, bind the mock instance into the container. The container will then use the mock instance instead of creating the object.

use App\Service;
use Mockery;
use Mockery\MockInterface;

test('something can be mocked', function () {
    $this->instance(
        Service::class,
        Mockery::mock(Service::class, function (MockInterface $mock) {
            $mock->expects('process');
        })
    );
});

use App\Service;
use Mockery;
use Mockery\MockInterface;

public function test_something_can_be_mocked(): void
{
    $this->instance(
        Service::class,
        Mockery::mock(Service::class, function (MockInterface $mock) {
            $mock->expects('process');
        })
    );
}

The `mock()` method

Laravel’s test case base class provides a mock() method that lets you write the same thing more concisely.

use App\Service;
use Mockery\MockInterface;

$mock = $this->mock(Service::class, function (MockInterface $mock) {
    $mock->expects('process');
});

The `partialMock()` method

When you want to mock only some methods of an object, use partialMock(). Methods that aren’t mocked are executed as usual.

use App\Service;
use Mockery\MockInterface;

$mock = $this->partialMock(Service::class, function (MockInterface $mock) {
    $mock->expects('process');
});

The `spy()` method

Spies are similar to mocks, but interactions are verified after the code has run. While a mock declares “this method should be called” in advance, a spy checks “was this method called?” afterward.

use App\Service;

$spy = $this->spy(Service::class);

// ... run the code under test ...

$spy->shouldHaveReceived('process');

Mocking facades

Unlike ordinary static method calls, facades can be mocked. They have the same testability as dependency injection while offering a concise syntax. As an example, consider a controller that uses the cache.

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Cache;

class UserController extends Controller
{
    /**
     * Return a list of all users in the application.
     */
    public function index(): array
    {
        $value = Cache::get('key');

        return [
            // ...
        ];
    }
}

To mock the get method of the Cache facade, use expects().

<?php

use Illuminate\Support\Facades\Cache;

test('get index', function () {
    Cache::expects('get')
        ->with('key')
        ->andReturn('value');

    $response = $this->get('/users');

    // ...
});

<?php

namespace Tests\Feature;

use Illuminate\Support\Facades\Cache;
use Tests\TestCase;

class UserControllerTest extends TestCase
{
    public function test_get_index(): void
    {
        Cache::expects('get')
            ->with('key')
            ->andReturn('value');

        $response = $this->get('/users');

        // ...
    }
}

Do not mock the Request facade. Instead, pass input to HTTP test methods like get and post. Similarly, instead of mocking the Config facade, call Config::set() in your test.

Facade spies

To watch a facade with a spy, call the spy() method on the corresponding facade. Spies are convenient when you want to verify interactions after the code has run.

<?php

use Illuminate\Support\Facades\Cache;

test('values are stored in cache', function () {
    Cache::spy();

    $response = $this->get('/');

    $response->assertStatus(200);

    Cache::shouldHaveReceived('put')->with('name', 'Taylor', 10);
});

use Illuminate\Support\Facades\Cache;

public function test_values_are_stored_in_cache(): void
{
    Cache::spy();

    $response = $this->get('/');

    $response->assertStatus(200);

    Cache::shouldHaveReceived('put')->with('name', 'Taylor', 10);
}

Manipulating time

When testing time-dependent logic, it’s helpful to change what now() or Carbon::now() returns. Laravel’s feature test base class provides helpers for manipulating time.

`travel()` — move through time

test('time can be manipulated', function () {
    // Move into the future
    $this->travel(5)->milliseconds();
    $this->travel(5)->seconds();
    $this->travel(5)->minutes();
    $this->travel(5)->hours();
    $this->travel(5)->days();
    $this->travel(5)->weeks();
    $this->travel(5)->years();

    // Move into the past
    $this->travel(-5)->hours();

    // Move to a specific moment
    $this->travelTo(now()->subHours(6));

    // Return to the current time
    $this->travelBack();
});

public function test_time_can_be_manipulated(): void
{
    // Move into the future
    $this->travel(5)->milliseconds();
    $this->travel(5)->seconds();
    $this->travel(5)->minutes();
    $this->travel(5)->hours();
    $this->travel(5)->days();
    $this->travel(5)->weeks();
    $this->travel(5)->years();

    // Move into the past
    $this->travel(-5)->hours();

    // Move to a specific moment
    $this->travelTo(now()->subHours(6));

    // Return to the current time
    $this->travelBack();
}

Time travel with closures

If you pass a closure to a time-travel method, time is frozen at the specified moment while the closure runs, and returns to the original time after it completes.

$this->travel(5)->days(function () {
    // Test in the state 5 days in the future
});

$this->travelTo(now()->subDays(10), function () {
    // Test at a specific moment
});

`freezeTime()` — stop time

freezeTime() freezes the current time. freezeSecond() freezes time at the beginning of the current second.

use Illuminate\Support\Carbon;

// Freeze time, run a closure, and resume afterward
$this->freezeTime(function (Carbon $time) {
    // ...
});

// Freeze at the start of the current second and run a closure
$this->freezeSecond(function (Carbon $time) {
    // ...
});

Practical example: locking inactive threads

Time manipulation is helpful for testing features like a forum where posts get locked after a period of inactivity.

use App\Models\Thread;

test('forum threads lock after one week of inactivity', function () {
    $thread = Thread::factory()->create();

    $this->travel(1)->week();

    expect($thread->isLockedByInactivity())->toBeTrue();
});

use App\Models\Thread;

public function test_forum_threads_lock_after_one_week_of_inactivity(): void
{
    $thread = Thread::factory()->create();

    $this->travel(1)->week();

    $this->assertTrue($thread->isLockedByInactivity());
}

Time manipulation methods like travel() are only available in feature tests (classes that extend Tests\TestCase). They are not available on PHPUnit’s base TestCase.

Method reference

Method	Description
`$this->mock(Class::class, fn)`	Create a full mock of a class and register it in the container
`$this->partialMock(Class::class, fn)`	Mock only some methods
`$this->spy(Class::class)`	Create a spy and register it in the container
`$this->instance(Class::class, $mock)`	Register an arbitrary mock instance in the container
`Facade::expects('method')`	Mock a facade method
`Facade::spy()`	Watch a facade with a spy
`$spy->shouldHaveReceived('method')`	Assert that a method was called on the spy

Time manipulation

Method	Description
`$this->travel(n)->unit()`	Move time by the specified unit
`$this->travelTo(Carbon)`	Move to a specific moment
`$this->travelBack()`	Return to the current time
`$this->freezeTime(fn)`	Freeze time and run a closure
`$this->freezeSecond(fn)`	Freeze at the start of the second and run a closure

Getting Started

Basics

Request Handling

Database

Authentication

Helpers and External Communication

Testing and Deployment

AI Development Support

Mocking

Why use mocks

Mocking objects

The `mock()` method

The `partialMock()` method

The `spy()` method

Mocking facades

Facade spies

Manipulating time

`travel()` — move through time

Time travel with closures

`freezeTime()` — stop time

Practical example: locking inactive threads

Method reference

Mocking

Time manipulation

​Why use mocks

​Mocking objects

​The mock() method

​The partialMock() method

​The spy() method

​Mocking facades

​Facade spies

​Manipulating time

​travel() — move through time

​Time travel with closures

​freezeTime() — stop time

​Practical example: locking inactive threads

​Method reference

​Mocking

​Time manipulation

Why use mocks

Mocking objects

The `mock()` method

The `partialMock()` method

The `spy()` method

Mocking facades

Facade spies

Manipulating time

`travel()` — move through time

Time travel with closures

`freezeTime()` — stop time

Practical example: locking inactive threads

Method reference

Mocking

Time manipulation