Skip to main content
Copy for LLM

Pest Browser-Test Setup

Pest's browser plugin (pestphp/pest-plugin-browser) drives a real browser through Playwright. It lets you write end-to-end tests against any WireKit-using Laravel app — mobile-viewport rendering, click flows, animation behavior, JavaScript errors — all in PHP.

Follow the steps top-to-bottom and you should have a green smoke test inside one setup pass.

Prerequisites

Tool Minimum version
PHP 8.4
Composer 2.5
Node.js 20 LTS
npm 10
WireKit 2.0.0

Step 1 — Install the plugin

composer require pestphp/pest-plugin-browser --dev

The Composer plugin pestphp/pest-plugin writes a vendor/pest-plugins.json manifest after each install. Composer runs it only when allow-plugins in your composer.json permits it (Composer asks the first time) and the install did not pass --no-plugins. If the file is missing, write it yourself:

composer pest:dump-plugins

You can verify the file exists:

test -f vendor/pest-plugins.json && echo "OK" || echo "missing"

Step 2 — Install Playwright

The plugin drives Playwright, which you install from npm, together with the Chromium binary:

# 1. Add Playwright to your project. It is a dev dependency — the driver runs your
#    tests, it never ships to a browser.
npm install playwright@latest --save-dev

# 2. Download the Chromium binary itself. The npm package is the driver only, so
#    without this step every browser test fails on a missing executable.
npx playwright install chromium

The first run downloads the browser binaries; later runs reuse the cached install.

Step 3 — Wire up tests/Pest.php

Add the Browser suite extension to your tests/Pest.php:

<?php

declare(strict_types=1);

use Tests\TestCase;

pest()->extend(TestCase::class)
    ->in('Feature');

pest()->extend(TestCase::class)
    ->in('Browser');

Both suites share the same Tests\TestCase base class.

Step 4 — Verify your phpunit.xml

The browser plugin spins up an HTTP server to serve your Laravel app during tests. That server needs the same Laravel environment variables your normal app uses, especially:

<phpunit>
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="APP_KEY" value="base64:YOUR_TEST_KEY_HERE"/>
        <env name="DB_CONNECTION" value="sqlite"/>
        <env name="DB_DATABASE" value=":memory:"/>
        <env name="SESSION_DRIVER" value="array"/>
        <env name="CACHE_STORE" value="array"/>
    </php>
</phpunit>

Without APP_KEY, every page renders 500 Server Error (No application encryption key has been specified). Generate a fresh key for your test environment:

php artisan key:generate --show

Copy the output into the APP_KEY env entry above.

Step 5 — Build your front-end

Run a production build so the Vite manifest exists before the test suite starts:

npm run build

This populates public/build/manifest.json, which Blade's @vite() directive resolves to. Without the manifest, the test pages crash with a ViewException.

Step 6 — Write a smoke test

Create tests/Browser/SmokeTest.php:

<?php

declare(strict_types=1);

it('homepage renders without JavaScript errors', function () {
    // 1. The plugin's own listener is attached at navigation, so it is already
    //    watching while the page renders — which is when the errors worth catching
    //    happen.
    $this->visit('/')->assertNoJavascriptErrors();
});

assertNoJavascriptErrors() records the errors nothing caught, the window's error event. It does not see a console.error call or a promise rejection nobody handled.

Do not hand-roll the capture after the visit

The obvious way to catch console.error as well is to visit the page, then overwrite console.error with a collector and read the array back afterwards. It fails green: the hook goes on after visit() returns, so every error logged while the page was rendering — the ones that matter — happened before anything was listening. A recorder that should see them has to be the first script in the <head> of the page under test, rendered there in your testing environment only, and read back with script().

Run it:

vendor/bin/pest tests/Browser/SmokeTest.php

You should see one passing test.

Mobile-Viewport Testing

Switch the rendering viewport with the device API on the visited page:

it('landing page renders correctly on iPhone 14 Pro', function () {
    // 1. Hold the page a call returns, not the device builder: in some versions of the
    //    plugin every call on the builder opens a page of its own.
    $page = $this->visit('/')->on()->iPhone14Pro()->wait(1);

    expect($page->script('(() => window.innerWidth)()'))->toBe(393);
});

it('landing page renders correctly on iPad Pro', function () {
    $page = $this->visit('/')->on()->iPadPro()->wait(1);

    expect($page->script('(() => window.innerWidth)()'))->toBe(1024);
});

The full device catalog includes iPhone 14/15/15Pro/SE, iPad Pro/Mini, Pixel 6a/7/8, Galaxy S22/S23/S24Ultra, plus macBook 14/16 and a generic desktop() / mobile() selector. Browse vendor/pestphp/pest-plugin-browser/src/Api/On.php for the full set.

Reduced motion

Playwright reports prefers-reduced-motion: no-preference unless told otherwise, and the plugin offers no switch for that media feature. To test the reduced path of WireKit's components, render the page with data-reduce-motion="reduce" on <html>: WireKit's stylesheet and scripts follow the attribute as they follow the system setting. Setting it with script() after the page loaded reaches the stylesheet; a component that read the setting while it started keeps what it read.

Known Issues

Issue 1 — vendor/pest-plugins.json missing

When Composer did not run the pestphp/pest-plugin plugin (it is not in allow-plugins, or the install passed --no-plugins), the manifest is never written, and every $this->visit(...) call fails with:

Call to a member function sendText() on null
  at vendor/pestphp/pest-plugin-browser/src/Playwright/Client.php:87

Fix: allow the plugin in composer.json, or run composer pest:dump-plugins after the install.

Issue 2 — Playwright server process leaks across test runs

The Node process the plugin starts for Playwright (playwright run-server) can outlive the Pest process, and the next run starts a fresh one on another port, so memory accumulates.

Workaround: add a post-run cleanup step in CI:

vendor/bin/pest tests/Browser/
pkill -9 -f playwright

In a long-running CI container the pkill line keeps the leftover servers from running it out of memory.

Cross-References

Was this page helpful?

Thank you for your feedback!

Voting requires cookies or local storage. What we store