Download the PHP package saucebase/laravel-playwright without Composer

Laravel Playwright

This repository contains a Laravel and a Playwright library to help you write E2E tests for your Laravel application using Playwright. It adds a set of endpoints to your Laravel application to allow Playwright to interact with it. You can do the following from your Playwright tests:

• Run artisan commands
• Create models using factories
• Run database queries
• Run PHP functions
• Update Laravel config while a test is running (until the test ends and calls tearDown).
• Register a boot function to run on every subsequent Laravel request in the test — useful for swapping service bindings.
• Traveling to a specific time in the application during the test

📦 Installation

On Laravel side, install the package via composer:

On Playwright side, install the package via npm:

⚙️ Laravel Config

Publish the config file:

This creates config/laravel-playwright.php with the following options:

💡 Example

If you need a good and more complex example of a repository using this package, look at https://github.com/saucebase-dev/saucebase

🎭 Playwright Config

Set use.laravelBaseUrl in your playwright.config.ts to the base URL of your testing endpoints (your application URL + the prefix from Laravel config).

If you use TypeScript, include the LaravelOptions type in the defineConfig function.

🔒 Security

The package supports an optional shared secret to prevent unauthorized access to the testing endpoints.

Laravel .env:

playwright.config.ts:

When configured, the TypeScript client sends the secret as an X-Playwright-Secret header on every request. Laravel returns 401 Unauthorized if the header is missing or doesn't match. When PLAYWRIGHT_SECRET is not set, all requests pass through (backwards compatible).

🧪 Setting up tests

In your Playwright tests, swap the test import from @playwright/test to @saucebase/laravel-playwright.

Note: In practice, it is not recommended to import from @saucebase/laravel-playwright directly in every test file if you have many. Instead, create your own test fixture extending test from @saucebase/laravel-playwright and import that fixture in your tests.

🚀 Basic Usage

🔄 Dynamic Configuration

You can update Laravel config for ALL subsequent requests until the test ends.

🔁 Boot Functions

Boot functions let you run PHP code at the start of every subsequent Laravel request during a test. This is the right tool when you need a service binding or side effect to be in place for browser-driven requests — not just during test setup.

A common use case is swapping a real external service (payment gateway, mailer, SMS provider) with a fake for the duration of a test.

1. Create a helper class in your app (e.g. app/E2EHelpers.php):

2. Register it in your Playwright test:

Why not use callFunction instead? callFunction runs once and returns. registerBootFunction runs at the start of every request the browser makes during the test, so service bindings registered in the boot phase are in place for the full request lifecycle — including middleware, controllers, and event listeners.

Note: The helper class only needs to exist in your local and testing environments. You can guard it with an environment check or keep it out of production deployments entirely.

🙏 Credits

This package was inspired by hyvor/laravel-playwright