@saucebase/laravel-playwright 2.3.0 → 2.3.1

package/README.md

@@ -1,99 +1,368 @@
-# Laravel Playwright
+# Laravel and Playwright E2E Testing
 
+A **Laravel and Playwright library** for end-to-end (E2E) browser testing.
 
-This repository contains a Laravel and a Playwright library to help you write E2E tests for your Laravel application using [Playwright](https://playwright.dev/). 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:
+Use Laravel factories, Artisan commands, database queries, configuration and time travel from your [Playwright](https://playwright.dev/) 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
+This package has two parts: a Laravel package that exposes testing endpoints, and a TypeScript fixture that calls them. Run your tests against a dedicated server and database; the fixture cleans up each test's configuration, clock and boot functions automatically.
 
-## 📦 Installation
+## Contents
 
-On Laravel side, install the package via composer:
+- [Requirements](#requirements)
+- [Quick start](#quick-start)
+- [API reference](#api-reference)
+- [Reusable fixtures and PHP helpers](#reusable-fixtures-and-php-helpers)
+- [Database setup and parallel tests](#database-setup-and-parallel-tests)
+- [Configuration, time and boot functions](#configuration-time-and-boot-functions)
+- [Environment and server configuration](#environment-and-server-configuration)
+- [Security and custom endpoints](#security-and-custom-endpoints)
+- [CI](#ci)
+- [Troubleshooting](#troubleshooting)
+- [Laravel Boost](#laravel-boost)
+- [Upgrading from v1](#upgrading-from-v1)
+
+## Requirements
+
+- PHP 8.3+
+- Laravel 12 or 13
+- Node.js 22+
+- Playwright ^1.58.2
+
+## Quick start
+
+Run these commands from your existing Laravel application's root.
+
+### 1. Install both packages and a browser
 
 ```bash
 composer require --dev saucebase/laravel-playwright
+npm install --save-dev @playwright/test @saucebase/laravel-playwright
+npx playwright install chromium
 ```
 
-On Playwright side, install the package via npm:
+Laravel discovers the provider automatically. To publish the configuration:
 
 ```bash
-npm install @saucebase/laravel-playwright --save-dev
+php artisan vendor:publish --tag=laravel-playwright-config
 ```
 
-## ⚙️ Laravel Config
+This creates `config/laravel-playwright.php`.
 
-Publish the config file:
+### 2. Create the test environment
 
 ```bash
-php artisan vendor:publish --tag=laravel-playwright-config
+php artisan playwright:env
 ```
 
-This creates `config/laravel-playwright.php` with the following options:
+This creates `.env.e2e` from `.env`, with a separate SQLite database (requires PHP’s SQLite extension), `APP_ENV=e2e`, and `APP_URL=http://localhost:8100`.
 
-```php
-return [
-    /**
-     * The prefix for the testing endpoints used to interact with Playwright.
-     * Make sure to update `use.laravelBaseUrl` in playwright.config.ts if you change this.
-     */
-    'prefix' => env('PLAYWRIGHT_PREFIX', 'playwright'),
+> [!WARNING]
+> `.env.e2e` contains your app's secrets. Add these entries to `.gitignore`:
+>
+> ```gitignore
+> .env.e2e
+> .env.e2e.backup
+> /test-results/
+> /playwright-report/
+> ```
 
-    /**
-     * The environments in which the testing endpoints are enabled.
-     * CAUTION: the endpoints run arbitrary PHP and SQL. Never enable them in
-     * production, nor in `local`, the environment your own dev server runs in.
-     */
-    'environments' => ['e2e', 'testing'],
+Use a dedicated test database, never your development or production database.
 
-    /**
-     * Optional secret token to authenticate Playwright requests.
-     * Set PLAYWRIGHT_SECRET in your .env and laravelSecret in playwright.config.ts.
-     */
-    'secret' => env('PLAYWRIGHT_SECRET', null),
-];
+### 3. Configure Playwright
+
+Create or update `playwright.config.ts` in the app root:
+
+```ts
+import { defineConfig } from '@playwright/test';
+import { laravelServer, type LaravelOptions } from '@saucebase/laravel-playwright';
+
+export default defineConfig<LaravelOptions>({
+    testDir: './tests/e2e',
+    use: {
+        baseURL: 'http://localhost:8100',
+    },
+    webServer: laravelServer(),
+});
 ```
 
-## 💡 Example
+`laravelServer()` migrates the E2E database, starts Laravel in the `e2e` environment, and waits for it to respond. Playwright manages the server's lifecycle. You do not need to start Herd, Docker or a separate Artisan server for this suite.
 
-If you need a good and more complex example of a repository using this package, look at https://github.com/saucebase-dev/saucebase
+Keep `baseURL` equal to `APP_URL` in `.env.e2e`. The client automatically uses `${baseURL}/playwright` for its testing endpoints.
 
-## 🎭 Playwright Config
+### 4. Write your first test
 
-Set `use.laravelBaseUrl` in your `playwright.config.ts` to the base URL of your testing endpoints (your application URL + the `prefix` from Laravel config).
+Create `tests/e2e/example.spec.ts`:
 
 ```ts
-export default defineConfig({
-    /** ...other config */
-    use: {
-        laravelBaseUrl: 'http://localhost/playwright',
-        laravelSecret: process.env.PLAYWRIGHT_SECRET,  // optional
-    },
+import { expect } from '@playwright/test';
+import { test } from '@saucebase/laravel-playwright';
+
+test('opens the app and creates a user', async ({ page, laravel }) => {
+    const user = await laravel.factory('User', {
+        email: `e2e-${crypto.randomUUID()}@example.com`,
+    });
+
+    const rows = await laravel.select(
+        'SELECT id FROM users WHERE email = :email',
+        { email: user.email },
+    );
+
+    expect(rows).toEqual([{ id: user.id }]);
+
+    const response = await page.goto('/');
+    expect(response?.status()).toBe(200);
 });
 ```
 
-If you use TypeScript, include the `LaravelOptions` type in the `defineConfig` function.
+Import `test` from this package to get the `laravel` fixture; import `expect` from Playwright. Use your app's factory and page URL in the example.
+
+### 5. Run it
+
+```bash
+npx playwright test
+```
+
+You should see one passing test. For interactive debugging, use `npx playwright test --ui`.
+
+If your app requires compiled frontend assets, run `npm run build` before testing.
+
+## API reference
+
+All methods below are available on the `laravel` fixture and return promises.
+
+| Method | Purpose | Result |
+| --- | --- | --- |
+| `artisan(command, parameters?)` | Run an Artisan command | `{ code, output }` |
+| `factory(model, attributes?, count?)` | Create models using their factories | One object, or an array when `count` is provided |
+| `select(sql, bindings?, options?)` | Read database rows | Array of objects |
+| `query(sql, bindings?, options?)` | Execute a database statement | `{ success }` |
+| `truncate(connections?)` | Truncate tables on the selected connections | Await completion |
+| `callFunction<T>(callable, arguments?)` | Call PHP once and decode its JSON result | `T` |
+| `config(key, value)` | Change configuration for this test | Await completion |
+| `travel(datetime)` | Set Laravel's clock for this test | Await completion |
+| `registerBootFunction(callable)` | Run PHP at boot on subsequent requests in this test | Await completion |
+| `tearDown()` | Remove this test's config, clock and boot functions | Called automatically by the fixture |
+
+### Artisan
+
+Pass options in the command string:
 
 ```ts
-import type { LaravelOptions } from '@saucebase/laravel-playwright';
+const result = await laravel.artisan('db:seed --class=DatabaseSeeder');
+expect(result.code).toBe(0);
+```
 
-export default defineConfig<LaravelOptions>({
-    use: {
-        laravelBaseUrl: 'http://localhost/playwright',
-        laravelSecret: process.env.PLAYWRIGHT_SECRET,  // optional
+Commands run from your application's root. Inspect `code` to check whether the command succeeded. Do not pass CLI tokens such as `['--class', 'DatabaseSeeder']` as the second argument: Laravel expects named arguments and options, not a token list.
+
+### Factories
+
+```ts
+const user = await laravel.factory('User', {
+    email: `e2e-${crypto.randomUUID()}@example.com`,
+});
+const users = await laravel.factory('User', {}, 3);
+const otherUser = await laravel.factory(String.raw`App\Models\User`);
+```
+
+A short name resolves to `App\Models\<Name>`. For a module or package model, pass its full class name. Models must expose Laravel's `factory()` method. Use a PHP helper for factory states or relationships.
+
+### Queries
+
+```ts
+const users = await laravel.select(
+    'SELECT id, email FROM users WHERE email = :email',
+    { email: user.email },
+);
+
+await laravel.query('UPDATE users SET name = ? WHERE id = ?', ['Updated', user.id]);
+```
+
+Both methods accept a third argument `{ connection: 'connection_name' }`. `query()` also accepts `{ unprepared: true }` for raw statements; it cannot be combined with bindings. Use bindings for values.
+
+### PHP functions
+
+```ts
+const appName = await laravel.callFunction<string>('config', ['app.name']);
+const credentials = await laravel.callFunction<{ email: string; password: string }>(
+    String.raw`Tests\Support\E2eUsers::create`,
+);
+```
+
+Pass positional arguments as an array, or named arguments as an object. The callable must exist and be autoloadable in the app. Results must be JSON-serializable; TypeScript's generic describes the expected shape, it does not validate the response.
+
+## Reusable fixtures and PHP helpers
+
+As a suite grows, give it one fixture entry point. Keep application-specific setup in PHP helpers instead of repeating SQL or model details in TypeScript.
+
+For example, create `tests/Support/E2eUsers.php`. A standard Laravel app already autoloads the `Tests\` namespace for development:
+
+```php
+<?php
+
+namespace Tests\Support;
+
+use App\Models\User;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Str;
+
+class E2eUsers
+{
+    /** @return array{email: string, password: string} */
+    public static function create(): array
+    {
+        $password = Str::random(24);
+        $user = User::factory()->create([
+            'email' => 'e2e-'.Str::uuid().'@example.com',
+            'password' => Hash::make($password),
+        ]);
+
+        return ['email' => $user->email, 'password' => $password];
+    }
+}
+```
+
+Create `tests/e2e/fixtures.ts`:
+
+```ts
+import { test as base } from '@saucebase/laravel-playwright';
+export { expect } from '@playwright/test';
+
+type Credentials = { email: string; password: string };
+
+export const test = base.extend<{ credentials: Credentials }>({
+    credentials: async ({ laravel }, use) => {
+        const credentials = await laravel.callFunction<Credentials>(
+            String.raw`Tests\Support\E2eUsers::create`,
+        );
+        await use(credentials);
     },
 });
 ```
 
-## 🏝️ A dedicated environment
+Then import your fixture in specs:
+
+```ts
+import { test, expect } from './fixtures';
+
+test('prepares an account', async ({ credentials, laravel }) => {
+    const users = await laravel.select(
+        'SELECT email FROM users WHERE email = :email',
+        { email: credentials.email },
+    );
+    expect(users).toEqual([{ email: credentials.email }]);
+});
+```
+
+Each test gets a different user. Build an app-specific `loginAs` fixture on top once your app has an authentication flow; a plain Laravel installation has no login page.
+
+You can also fail tests on uncaught browser exceptions with an automatic fixture:
+
+```ts
+import { expect } from '@playwright/test';
+import { test as base } from './fixtures';
+
+export const test = base.extend<{ failOnPageError: void }>({
+    failOnPageError: [async ({ page }, use) => {
+        const errors: string[] = [];
+        page.on('pageerror', error => errors.push(error.message));
+        await use();
+        expect(errors, 'uncaught browser errors').toEqual([]);
+    }, { auto: true }],
+});
+```
+
+These patterns are adapted from [Saucebase Core's fixtures](https://github.com/saucebase-dev/core/blob/main/stubs/app/tests/e2e/fixtures/index.ts). See [Saucebase](https://github.com/saucebase-dev/saucebase) for a larger application example. Roles, billing accounts and module helpers in that app are application features, not requirements of this package.
+
+## Database setup and parallel tests
+
+`laravelServer()` runs migrations; it does **not** reset your database on every run. Factory-created rows survive test teardown. Configuration, time and boot functions are isolated per test, but database rows are shared.
+
+For a clean database at the start of each suite, create `tests/e2e/database.setup.ts`:
+
+```ts
+import { expect } from '@playwright/test';
+import { test as setup } from '@saucebase/laravel-playwright';
+
+setup('reset the E2E database', async ({ laravel }) => {
+    const result = await laravel.artisan('migrate:fresh --seed');
+    expect(result.code).toBe(0);
+});
+```
+
+Add projects to your existing `defineConfig` call:
+
+```ts
+projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    { name: 'chromium', testMatch: /.*\.spec\.ts/, dependencies: ['setup'] },
+],
+```
+
+**This deletes all data in the E2E database.** Never run `migrate:fresh` or `truncate()` inside tests that execute alongside other tests. Reset once before the workers start.
+
+Use unique emails and identifiers for mutable records. Shared fixed-email accounts should be seeded once in setup and only read by tests. Per-process Faker uniqueness does not guarantee uniqueness across separate HTTP requests.
+
+`await laravel.truncate()` truncates the default connection; pass an array of connection names to select others.
+
+## Configuration, time and boot functions
+
+```ts
+import { test } from '@saucebase/laravel-playwright';
+import { expect } from '@playwright/test';
+
+test('changes config and time', async ({ laravel }) => {
+    await laravel.config('app.timezone', 'Europe/Dublin');
+    await laravel.travel('2026-01-01 12:00:00');
+    expect(await laravel.callFunction<string>('config', ['app.timezone']))
+        .toBe('Europe/Dublin');
+});
+```
+
+Changes apply to subsequent requests carrying this test's ID, until the fixture calls `tearDown()`. Time travel changes Laravel's clock, not the browser's JavaScript clock.
+
+### Boot functions
+
+`callFunction()` runs once. `registerBootFunction()` registers a callable that runs at the start of subsequent Laravel requests in the test. Use it when browser requests need a service binding or fake installed on every request.
+
+For example, create `tests/Support/E2eBoot.php`:
+
+```php
+<?php
 
-Run the suite on its own server and database, so it never touches your dev app or its data. This works the same however you serve the app day to day: Herd, Valet, Sail, Docker or `artisan serve`.
+namespace Tests\Support;
+
+use Illuminate\Support\Facades\Mail;
+
+class E2eBoot
+{
+    public static function fakeMail(): void
+    {
+        Mail::fake();
+    }
+}
+```
+
+Register it before navigating to the app:
+
+```ts
+await laravel.registerBootFunction(String.raw`Tests\Support\E2eBoot::fakeMail`);
+await page.goto('/');
+```
+
+The fake is recreated for each request. Its recorded messages do not persist across requests; use this to prevent delivery, not to assert mail from an earlier request. The same pattern can bind your application's external-service interface to a fake implementation.
+
+### Request isolation
+
+The fixture creates a test ID and sends `X-Playwright-Test` on its Laravel calls and browser requests to the app. State is stored in `storage/framework/playwright/<test-id>.json` and removed automatically at teardown.
+
+- Parallel tests do not see or delete each other's config, time or boot functions.
+- The browser header matches the `baseURL` host and its subdomains; third-party requests are untouched. Override this with `use.laravelIsAppUrl: (url: URL) => boolean`.
+- Custom routes intercepting app requests must call `route.fallback()`, not `route.continue()`, so the fixture can add the header.
+- Contexts you create with `browser.newContext()` do not receive the header automatically.
+- Requests without the ID, including external queue workers, do not see this state. A custom endpoint client must send the header itself.
+
+## Environment and server configuration
 
-**1. Create `.env.e2e`:**
 
 ```bash
 php artisan playwright:env
@@ -136,7 +405,7 @@ If the file exists, the command asks whether to back it up and replace it, repla
 
 Options: `php artisan playwright:env <environment> --url=http://localhost:9000`. Edit the file afterwards for anything else the suite needs. Keep `.env.e2e` out of git like `.env`, and in CI, run the command after creating `.env`.
 
-**2. Let Playwright start the server:**
+### Server options
 
 ```ts
 import { defineConfig } from '@playwright/test';
@@ -154,223 +423,97 @@ export default defineConfig<LaravelOptions>({
 - `APP_URL` is missing or not `http:`. `artisan serve` has no TLS.
 - The Playwright process already has another `APP_ENV`. The server inherits the process's environment, and real environment variables override any env file, so `import 'dotenv/config'` (which loads `.env`) would give the server your dev database. To read values from `.env.e2e` in the config, use `config({ path: '.env.e2e' })` from dotenv.
 
-**Subdomains and multi-tenancy.** Chromium resolves every `*.localhost` to your machine, so `http://acme.localhost:8100` reaches the same server with no DNS or hosts-file setup. To use a real wildcard host instead (Herd or Valet `*.app.test`), skip `laravelServer()` and point `baseURL` at that host, served with `APP_ENV=e2e`.
-
-## 🔒 Security
-
-The package supports an optional shared secret to prevent unauthorized access to the testing endpoints.
+### Subdomains and multi-tenancy
+ Chromium resolves every `*.localhost` to your machine, so `http://acme.localhost:8100` reaches the same server with no DNS or hosts-file setup. To use a real wildcard host instead (Herd or Valet `*.app.test`), skip `laravelServer()` and point `baseURL` at that host, served with `APP_ENV=e2e`.
 
-**Laravel `.env`:**
-```
-PLAYWRIGHT_SECRET=some-secret
-```
+## Security and custom endpoints
 
-**`playwright.config.ts`:**
-```ts
-use: {
-    laravelSecret: process.env.PLAYWRIGHT_SECRET,
-},
-```
+The endpoints can execute PHP, SQL and Artisan commands. They are enabled only in `e2e` and `testing` by default. Never enable them in production or on your regular `local` development server. Install the Composer package as a development dependency.
 
-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).
+To customize the defaults:
 
-## 🧪 Setting up tests
-
-In your Playwright tests, swap the `test` import from `@playwright/test` to `@saucebase/laravel-playwright`.
-
-```diff
-- import { test } from '@playwright/test';
-+ import { test } from '@saucebase/laravel-playwright';
-
-test('example', async ({ laravel }) => {
-    await laravel.artisan('migrate:fresh');
-});
+```bash
+php artisan vendor:publish --tag=laravel-playwright-config
 ```
 
-> **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](https://playwright.dev/docs/test-fixtures) extending `test` from `@saucebase/laravel-playwright` and import that fixture in your tests.
-
-## 🚀 Basic Usage
-
-```ts
-import { test } from '@saucebase/laravel-playwright';
-
-test('example', async ({ laravel }) => {
-
-    /** 🏃 RUN ARTISAN COMMANDS */
-    const output = await laravel.artisan('migrate:fresh');
-    /**
-     * output.code: number - The exit code of the command
-     * output.output: string - The output of the command
-     */
-    /** with parameters */
-    await laravel.artisan('db:seed', ['--class', 'DatabaseSeeder']);
-
-
-    /** 🗑️ TRUNCATE TABLES */
-    await laravel.truncate();
-    /** in specific DB connections */
-    await laravel.truncate(['connection1', 'connection2']);
-
-
-    /** 🏭 CREATE MODELS FROM FACTORIES */
-    /**
-     * Create a App\Models\User model
-     * user will be an object of the model
-     */
-    const user = await laravel.factory('User');
-    /** Create a App\Models\User model with attributes */
-    await laravel.factory('User', { name: 'John Doe' });
-    /**
-     * Create 5 App\Models\User models
-     * users will be an array of the models
-     */
-    const users = await laravel.factory('User', {}, 5);
-    /** Create a CustomModel model */
-    await laravel.factory('CustomModel');
-
-
-    /** 💾 RUN A DATABASE QUERY */
-    await laravel.query('DELETE FROM users');
-    /** with bindings */
-    await laravel.query('DELETE FROM users WHERE id = ?', [1]);
-    /** on a specific connection */
-    await laravel.query('DELETE FROM users', [], { connection: 'connection1' });
-    /** unprepared statement */
-    await laravel.query(`
-        DROP SCHEMA public CASCADE;
-        CREATE SCHEMA public;
-        GRANT ALL ON SCHEMA public TO public;
-    `, [], { unprepared: true });
-
-
-    /** 🔍 RUN A SELECT QUERY */
-    /** returns an array of objects */
-    const blogs = await laravel.select('SELECT * FROM blogs');
-    /** with bindings */
-    await laravel.select('SELECT * FROM blogs WHERE id = ?', [1]);
-    /** on a specific connection */
-    await laravel.select('SELECT * FROM blogs', {}, { connection: 'connection1' });
-
-
-    /** ⚙️ RUN A PHP FUNCTION */
-    /**
-     * Output is JSON encoded in Laravel and decoded in Playwright
-     * The following examples call this function:
-     * function sayHello($name) { return "Hello, $name!"; }
-     */
-    const funcOutput = await laravel.callFunction('sayHello');
-    /** with positional parameters */
-    await laravel.callFunction('sayHello', ['John']);
-    /** with named parameters */
-    await laravel.callFunction('sayHello', { name: 'John' });
-    /** static class method */
-    await laravel.callFunction("App\\MyAwesomeClass::method");
-
-});
-
+The published `config/laravel-playwright.php` contains:
 
+```php
+return [
+    'prefix' => env('PLAYWRIGHT_PREFIX', 'playwright'),
+    'environments' => ['e2e', 'testing'],
+    'secret' => env('PLAYWRIGHT_SECRET', null),
+];
 ```
 
-## 🔄 Dynamic Configuration
+For a custom prefix, set `use.laravelBaseUrl` to the complete endpoint base URL, for example `http://localhost:8100/test-api`.
 
-You can update Laravel config for every subsequent request **of the same test**, until the test ends.
+### Optional shared secret
 
-The state is kept per test. The `laravel` fixture gives each test an id and sends it in an `X-Playwright-Test` header, on its own calls and on the browser's requests to the app. The server applies a test's state only to requests that carry its id. Parallel tests never see or remove each other's config, time or boot functions, and requests without the header (your own browser, a queue worker) see none.
+Set `PLAYWRIGHT_SECRET` in `.env.e2e` and pass the same value as `use.laravelSecret`. The client sends `X-Playwright-Secret`; missing or incorrect secrets receive HTTP 401. Without a configured secret, no secret check is performed.
 
-- Only requests to the app carry the header: the `baseURL` host and its subdomains. Third-party requests (Stripe, CDNs) are left alone, so no CORS preflight fails. Override the match with the `laravelIsAppUrl: (url: URL) => boolean` option.
-- The header is added with `context.route()`. If you add your own route for app URLs, call `route.fallback()`, not `route.continue()`, so the header is still added.
-- A context you create yourself (`browser.newContext()`) doesn't get the header.
+Node does not automatically load Laravel's env file. You can read the value without loading the entire file into the process environment:
 
 ```ts
-import { test } from '@saucebase/laravel-playwright';
+import { readFileSync } from 'node:fs';
+import { parseEnv } from 'node:util';
 
-test('example', async ({ laravel }) => {
+const e2e = parseEnv(readFileSync('.env.e2e', 'utf8'));
 
-    /** 🔧 SET DYNAMIC CONFIG */
-    /**
-     * Persists for all subsequent requests until the test ends
-     * and tearDown is called (done automatically)
-     */
-    await laravel.config('app.timezone', 'America/Sao_Paulo');
-
-    /** ⏰ TRAVEL TO A TIME */
-    /** similar to Laravel's `travelTo` method */
-    await laravel.travel('2022-01-01 12:00:00');
-
-});
+// Inside defineConfig:
+use: {
+    baseURL: e2e.APP_URL,
+    laravelSecret: e2e.PLAYWRIGHT_SECRET,
+},
 ```
 
-## 🔁 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`):
-
-```php
-<?php
+Keep the test server bound to loopback when possible. A secret does not make these endpoints appropriate for a production deployment.
 
-namespace App;
+## CI
 
-use App\Services\PaymentGateway;
-use App\Services\FakePaymentGateway;
-use App\Services\Mailer;
-use App\Services\NullMailer;
+After checking out the app and installing a compatible PHP and Node version, a typical Linux CI job runs:
 
-class E2EHelpers
-{
-    /**
-     * Swap real services for fakes. Called at boot on every request in the test.
-     */
-    public static function useFakeServices(): void
-    {
-        app()->bind(PaymentGateway::class, FakePaymentGateway::class);
-        app()->bind(Mailer::class, NullMailer::class);
-    }
-}
+```bash
+composer install --no-interaction --prefer-dist
+npm ci
+cp .env.example .env
+php artisan key:generate --no-interaction
+php artisan playwright:env --no-interaction
+npm run build
+npx playwright install --with-deps chromium
+CI=true npx playwright test
 ```
 
-**2. Register it in your Playwright test:**
-
-```ts
-import { test } from '@saucebase/laravel-playwright';
-
-test('checkout with fake payment gateway', async ({ laravel, page }) => {
-
-    // Register once — runs at boot on every subsequent request this test makes
-    await laravel.registerBootFunction('App\\E2EHelpers::useFakeServices');
-
-    // From here, every page load and API call the browser makes will use the fakes
-    const user = await laravel.factory('User');
-    await laravel.artisan('db:seed', ['--class', 'ProductSeeder']);
-
-    await page.goto('/checkout');
-    await page.fill('[name="card_number"]', '4242424242424242');
-    await page.click('button[type="submit"]');
-
-    await expect(page.locator('.order-confirmation')).toBeVisible();
-
-});
-```
+Keep development dependencies installed. Set any application-specific E2E overrides before generating `.env.e2e`. The example assumes the standard Laravel `.env.example` and SQLite; apps requiring external services need their own CI configuration. `CI=true` prevents `laravelServer()` from reusing an existing server.
 
-> **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.
+## Troubleshooting
 
-> **Note:** The helper class only needs to exist in your `e2e` and `testing` environments. You can guard it with an environment check or keep it out of production deployments entirely.
+| Symptom | Check |
+| --- | --- |
+| Browser executable does not exist | Run `npx playwright install chromium` after installing or upgrading Playwright. |
+| 404 from `/playwright/*` | Use the E2E server, not your regular local server. Check the configured prefix and environment. |
+| 401 from a testing endpoint | Pass the same secret to Laravel and `use.laravelSecret`. |
+| Server startup times out | Check `storage/logs/laravel.log`, missing assets, and whether `APP_URL` responds successfully. |
+| Port already in use or requests reach the wrong app | Choose another port with `playwright:env --url=...` and update `baseURL`. Outside CI, an existing responding server is reused. |
+| `APP_ENV` conflict | Do not load `.env` into Node; use `.env.e2e` or leave the process environment alone. |
+| SQLite `database is locked` | Keep the generated DB_URL lock settings and use PHP 8.4+ for immediate transactions. Avoid concurrent suite-wide resets. |
+| Tests pass alone but fail together | Look for shared mutable rows, fixed unique values, or resets running during other tests. |
+| Config or time does not reach browser requests | Check custom route handlers, new browser contexts and the app-host match. |
+| Artisan reports an unknown numbered argument | Use a command string, not a CLI token array as the second argument. |
 
-## 🤖 Laravel Boost
+## Laravel Boost
 
-The package ships a [Laravel Boost](https://laravel.com/docs/boost) guideline and a `laravel-playwright-development` skill, covering the e2e environment, per-test state, subdomains and common failures. Boost asks before including third-party packages: pick `saucebase/laravel-playwright` in `php artisan boost:install`, or add it to `packages` in `boost.json` and run `php artisan boost:update`.
+The package ships a Laravel Boost guideline and a `laravel-playwright-development` skill covering environments, per-test state, subdomains and common failures. Select `saucebase/laravel-playwright` during `php artisan boost:install`, or add it to `packages` in `boost.json` and run `php artisan boost:update`.
 
-## ⬆️ Upgrading from v1
+## Upgrading from v1
 
-- **The endpoints are off in `local`.** The default `environments` is now `['e2e', 'testing']`. Serve the suite with `APP_ENV=e2e` (see [A dedicated environment](#️-a-dedicated-environment)). If you published the config, update `environments` there.
-- **Dynamic config, `travel()` and boot functions are per test.** State moved from `storage/laravel-playwright-config.json` to `storage/framework/playwright/<test-id>.json`, and only applies to requests that carry the test's `X-Playwright-Test` header. The fixture sends the header for you. If you call the endpoints from your own client, send it yourself; `dynamicConfig`, `travel` and `registerBootFunction` return 400 without it.
-- `DynamicConfig::set()`, `get()`, `getAll()`, `load()` and `delete()` now take the test id as their first argument.
-- **Artisan commands run from the application root**, like the CLI, rather than the web server's `public/`.
-- Requires Laravel 12 or 13.
+- The endpoints are disabled in `local`. Use the dedicated E2E environment. If you published config previously, change `environments` to `['e2e', 'testing']`.
+- Dynamic configuration, time travel and boot functions are per test. State moved from `storage/laravel-playwright-config.json` to `storage/framework/playwright/<test-id>.json`.
+- Custom clients must send `X-Playwright-Test`. State-changing endpoints return HTTP 400 without it; the supplied fixture handles it automatically.
+- `DynamicConfig::set()`, `get()`, `getAll()`, `load()` and `delete()` take the test ID as their first argument.
+- Artisan commands run from the application root.
+- Laravel 12 or 13 is required.
 
-## 🙏 Credits
+## Credits
 
-This package was inspired by [hyvor/laravel-playwright](https://github.com/hyvor/laravel-playwright)
+Inspired by [hyvor/laravel-playwright](https://github.com/hyvor/laravel-playwright).

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export declare class Laravel {
     readonly testId: string;
     constructor(baseUrl: string, request: APIRequestContext, secret?: string | undefined, testId?: string);
     call<T = unknown>(endpoint: string, data?: object): Promise<T>;
-    artisan(command: string, parameters?: string[]): Promise<{
+    artisan(command: string, parameters?: Record<string, string | number | boolean | (string | number)[]>): Promise<{
         code: number;
         output: string;
     }>;

package/dist/laravel-playwright.js

@@ -83,7 +83,7 @@ class f {
             `);
     return await n.json();
   }
-  async artisan(t, e = []) {
+  async artisan(t, e = {}) {
     return await this.call("/artisan", { command: t, parameters: e });
   }
   async truncate(t = []) {

package/dist/laravel-playwright.umd.cjs

@@ -2,4 +2,4 @@
                 Failed to call Laravel ${e}.
                 Status: ${s.status()}
                 Response: ${await s.text()}
-            `);return await s.json()}async artisan(e,t=[]){return await this.call("/artisan",{command:e,parameters:t})}async truncate(e=[]){return await this.call("/truncate",{connections:e})}async factory(e,t={},a){return await this.call("/factory",{model:e,count:a,attrs:t})}async query(e,t=[],a={}){const{connection:r=null,unprepared:s=!1}=a;if(s&&t.length>0)throw new Error("Cannot use unprepared with bindings");return await this.call("/query",{query:e,bindings:t,connection:r,unprepared:s})}async select(e,t={},a={}){const{connection:r=null}=a;return await this.call("/select",{query:e,bindings:t,connection:r})}async callFunction(e,t=[]){return await this.call("/function",{function:e,args:t})}async config(e,t){return await this.call("/dynamicConfig",{key:e,value:t})}async travel(e){return await this.call("/travel",{to:e})}async registerBootFunction(e){return await this.call("/registerBootFunction",{function:e})}async tearDown(){return await this.call("/tearDown")}}n.Laravel=w,n.TEST_HEADER=h,n.isAppUrl=v,n.laravelServer=y,n.test=P,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));
+            `);return await s.json()}async artisan(e,t={}){return await this.call("/artisan",{command:e,parameters:t})}async truncate(e=[]){return await this.call("/truncate",{connections:e})}async factory(e,t={},a){return await this.call("/factory",{model:e,count:a,attrs:t})}async query(e,t=[],a={}){const{connection:r=null,unprepared:s=!1}=a;if(s&&t.length>0)throw new Error("Cannot use unprepared with bindings");return await this.call("/query",{query:e,bindings:t,connection:r,unprepared:s})}async select(e,t={},a={}){const{connection:r=null}=a;return await this.call("/select",{query:e,bindings:t,connection:r})}async callFunction(e,t=[]){return await this.call("/function",{function:e,args:t})}async config(e,t){return await this.call("/dynamicConfig",{key:e,value:t})}async travel(e){return await this.call("/travel",{to:e})}async registerBootFunction(e){return await this.call("/registerBootFunction",{function:e})}async tearDown(){return await this.call("/tearDown")}}n.Laravel=w,n.TEST_HEADER=h,n.isAppUrl=v,n.laravelServer=y,n.test=P,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saucebase/laravel-playwright",
-  "version": "v2.3.0",
+  "version": "v2.3.1",
   "description": "Blends Laravel and Playwright into seamless E2E tests — factories, queries, artisan commands, and time travel.",
   "license": "MIT",
   "repository": {