How to record Pest browser tests as videos

You can record an existing Pest browser test as a video and watch it locally. This tutorial uses diff-stage/recorder, a free, open-source Pest plugin. The recorder runs on your machine. No hosted service or account is required.

A passing test tells you its assertions passed. The video lets you check what the user saw between those assertions. For a login change, that might be a confusing error message, a button moving as the form submits, or an unexpected screen before the dashboard.

01Check your browser test setup#

Start with a Pest browser test that already passes in your Laravel app. Browser tests open a real browser using visit(...). HTTP feature tests using $this->get(...) don't produce browser recordings.

Run the commands from your Laravel project folder, where composer.json lives. If your tests run inside Docker, run these commands inside that same container. Keep your existing test database, fixtures and asset build setup.

The recorder supports these specific versions of Pest's Browser plugin:

Check your installed versions before adding it:

composer show pestphp/pest
composer show pestphp/pest-plugin-browser

Recording uses Browser internals, so the recorder rejects other Browser versions. Browser 5 also requires PHP 8.4 or later and the sockets extension.

If your Browser version isn't listed, use a supported version and get your tests passing before recording. Don't change a working project's Playwright version just to follow this article.

If you don't have browser tests yet, follow Pest's browser testing setup first, using a supported Browser version and its Playwright pairing from the table. Return here once a browser test passes.

02Choose a test with something worth watching#

Use an existing test that clicks through a real journey, such as signing in or submitting a form. You don't need to change the test to record it. Already have one? Skip the example below and use your test's path in the recording step.

For example, this login test submits a form and checks that the user reaches the dashboard. It assumes your app has /login and /dashboard, fields named email and password, a Log in button and visible Dashboard text. Adjust those to match your app.

Before adding this example, configure tests/Browser to use Laravel's test case and database reset trait. If your tests/Pest.php already configures this directory, keep that configuration. Otherwise, add:

pest()->extend(Tests\TestCase::class)
    ->use(Illuminate\Foundation\Testing\RefreshDatabase::class)
    ->in('Browser');

Use a separate test database with disposable test accounts. RefreshDatabase resets the database used by your tests, so check that it isn't your development or live database.

Save the example in tests/Browser/LoginTest.php:

<?php

use App\Models\User;
use Illuminate\Support\Facades\Hash;

it('lets a user log in', function () {
    $user = User::factory()->create([
        'password' => Hash::make('test-password'),
    ]);

    visit('/login')
        ->type('email', $user->email)
        ->type('password', 'test-password')
        ->press('Log in')
        ->assertPathIs('/dashboard')
        ->assertSee('Dashboard')
        ->assertNoJavaScriptErrors();

    $this->assertAuthenticatedAs($user);
});

Anything visible in the browser can appear in the video, including typed values. Check the footage before sharing it.

Keep the assertions. The test checks that authentication worked, while the video shows the form submission and the page that follows it. The recording only shows this test's journey; it doesn't verify flows the test doesn't cover.

03Install the recorder and capture the test#

Add the recorder as a development dependency:

composer require --dev diff-stage/recorder:^0.3 -W

The -W option allows Composer to update related dependencies to satisfy Pest's requirements. Review the changes to your Composer manifest and lockfile.

Replace tests/Browser/LoginTest.php below with your existing browser test's path, or use it unchanged if you saved the example above. First run the test normally, then record it:

./vendor/bin/pest tests/Browser/LoginTest.php
./vendor/bin/pest tests/Browser/LoginTest.php --record-videos

Passing a file runs every test in that file. To record your whole browser suite, pass tests/Browser instead. For a first recording, a small file makes it easier to check the result.

The --record-videos flag comes from the recorder plugin. It isn't a built-in Pest option.

04Watch the recording#

Open your project's tests/Browser/Videos folder in your file manager. The recorder saves a video for each recorded test. Open one in a video player and watch the journey. For the login example, check that you can see the form, the submit action and the dashboard.

The files stay on your machine. Recording doesn't upload them anywhere.

Keep generated videos out of source control:

/tests/Browser/Videos/

Make the recording easy to review#

For a login PR, give the reviewer a specific question. For example: "The submit button now stays in place while signing in. Watch the form submit and the dashboard appear."

That is more useful than asking someone to watch an entire test suite. Pick the journey that reaches the changed behaviour and check the footage before sharing it.

Local recording includes pauses before actions. Don't add fixed waits to your test just to make the video slower. Wait for application state with assertions and let the recording tools handle reading time.

If no recording appears, check that you passed --record-videos, that the selected file contains browser tests and that your Pest and Browser versions match the supported pairings. If the test itself fails, fix its environment or behaviour before treating the footage as a successful demonstration.