Pest Browser-Test Setup
Pest's browser plugin (pestphp/) 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/ writes a
vendor/ 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/, 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/:
<?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();
});
assert records the errors nothing caught, the window's error
event. It does not see a console.error call or a promise rejection nobody handled.
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/ 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/ 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
- Authoring Custom Alpine Plugins — discipline for the plugins your browser tests will exercise.
- Console Output Baseline — what a clean install should emit (and what to filter out in your assertions).