@saucebase/laravel-playwright 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saucebase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# Laravel Playwright
+
+
+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:
+
+- 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:
+
+```bash
+composer require --dev saucebase/laravel-playwright
+```
+
+On Playwright side, install the package via npm:
+
+```bash
+npm install @saucebase/laravel-playwright --save-dev
+```
+
+## ⚙️ Laravel Config
+
+Publish the config file:
+
+```bash
+php artisan vendor:publish --tag=laravel-playwright-config
+```
+
+This creates `config/laravel-playwright.php` with the following options:
+
+```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'),
+
+    /**
+     * The environments in which the testing endpoints are enabled.
+     * CAUTION: Enabling testing endpoints in production is a critical security issue.
+     */
+    'environments' => ['local', 'testing'],
+
+    /**
+     * Optional secret token to authenticate Playwright requests.
+     * Set PLAYWRIGHT_SECRET in your .env and laravelSecret in playwright.config.ts.
+     */
+    'secret' => env('PLAYWRIGHT_SECRET', null),
+];
+```
+
+## 💡 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).
+
+```ts
+export default defineConfig({
+    /** ...other config */
+    use: {
+        laravelBaseUrl: 'http://localhost/playwright',
+        laravelSecret: process.env.PLAYWRIGHT_SECRET,  // optional
+    },
+});
+```
+
+If you use TypeScript, include the `LaravelOptions` type in the `defineConfig` function.
+
+```ts
+import type { LaravelOptions } from '@saucebase/laravel-playwright';
+
+export default defineConfig<LaravelOptions>({
+    use: {
+        laravelBaseUrl: 'http://localhost/playwright',
+        laravelSecret: process.env.PLAYWRIGHT_SECRET,  // optional
+    },
+});
+```
+
+## 🔒 Security
+
+The package supports an optional shared secret to prevent unauthorized access to the testing endpoints.
+
+**Laravel `.env`:**
+```
+PLAYWRIGHT_SECRET=some-secret
+```
+
+**`playwright.config.ts`:**
+```ts
+use: {
+    laravelSecret: process.env.PLAYWRIGHT_SECRET,
+},
+```
+
+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`.
+
+```diff
+- import { test } from '@playwright/test';
++ import { test } from '@saucebase/laravel-playwright';
+
+test('example', async ({ laravel }) => {
+    await laravel.artisan('migrate:fresh');
+});
+```
+
+> **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");
+
+});
+
+
+```
+
+## 🔄 Dynamic Configuration
+
+You can update Laravel config for **ALL** subsequent requests until the test ends.
+
+```ts
+import { test } from '@saucebase/laravel-playwright';
+
+test('example', async ({ laravel }) => {
+
+    /** 🔧 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');
+
+});
+```
+
+## 🔁 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
+
+namespace App;
+
+use App\Services\PaymentGateway;
+use App\Services\FakePaymentGateway;
+use App\Services\Mailer;
+use App\Services\NullMailer;
+
+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);
+    }
+}
+```
+
+**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();
+
+});
+```
+
+> **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](https://github.com/hyvor/laravel-playwright)

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { APIRequestContext } from '@playwright/test';
+export interface LaravelOptions {
+    /**
+     * The base URL to the endpoints
+     * @default <playwright-base-url>/playwright
+     */
+    laravelBaseUrl: string | undefined;
+    /**
+     * Optional secret token sent as X-Playwright-Secret header
+     */
+    laravelSecret: string | undefined;
+}
+interface LaravelFixtures {
+    laravel: Laravel;
+}
+export declare const test: import('playwright/test').TestType<import('playwright/test').PlaywrightTestArgs & import('playwright/test').PlaywrightTestOptions & LaravelFixtures & LaravelOptions, import('playwright/test').PlaywrightWorkerArgs & import('playwright/test').PlaywrightWorkerOptions>;
+export declare class Laravel {
+    private baseUrl;
+    private request;
+    private secret;
+    constructor(baseUrl: string, request: APIRequestContext, secret?: string | undefined);
+    call<T = unknown>(endpoint: string, data?: object): Promise<T>;
+    artisan(command: string, parameters?: string[]): Promise<{
+        code: number;
+        output: string;
+    }>;
+    truncate(connections?: (string | null)[]): Promise<unknown>;
+    factory(model: string, attrs?: Record<string, unknown>, count?: undefined): Promise<Record<string, unknown>>;
+    factory(model: string, attrs: Record<string, unknown>, count: number): Promise<Record<string, unknown>[]>;
+    query(query: string, bindings?: unknown[], options?: {
+        connection?: string | null;
+        unprepared?: boolean;
+    }): Promise<{
+        success: boolean;
+    }>;
+    select(query: string, bindings?: Record<string, unknown>, options?: {
+        connection?: string | null;
+    }): Promise<Record<string, unknown>[]>;
+    callFunction<T = unknown>(func: string, args?: unknown[] | Record<string, unknown>): Promise<T>;
+    /**
+     * Sets a laravel config value until tearDown is called (or the test ends)
+     */
+    config(key: string, value: unknown): Promise<unknown>;
+    /**
+     * Travel to a specific time
+     * ex: travel('2021-01-01 00:00:00')
+     */
+    travel(to: string): Promise<unknown>;
+    registerBootFunction(func: string): Promise<unknown>;
+    tearDown(): Promise<unknown>;
+}
+export {};

package/dist/laravel-playwright.js

@@ -0,0 +1,76 @@
+import { test as i } from "@playwright/test";
+const u = i.extend({
+  laravelBaseUrl: [void 0, { option: !0 }],
+  laravelSecret: [void 0, { option: !0 }],
+  laravel: async ({ laravelBaseUrl: s, laravelSecret: t, baseURL: a, request: e }, n) => {
+    const r = s || a + "/playwright", c = new l(r, e, t);
+    await n(c), await c.tearDown();
+  }
+});
+class l {
+  constructor(t, a, e = void 0) {
+    this.baseUrl = t, this.request = a, this.secret = e;
+  }
+  async call(t, a = {}) {
+    const e = this.baseUrl.replace(/\/$/, "") + t, n = { Accept: "application/json" };
+    this.secret && (n["X-Playwright-Secret"] = this.secret);
+    const r = await this.request.post(e, { data: a, headers: n });
+    if (r.status() !== 200)
+      throw new Error(`
+                Failed to call Laravel ${t}.
+                Status: ${r.status()}
+                Response: ${await r.text()}
+            `);
+    return await r.json();
+  }
+  async artisan(t, a = []) {
+    return await this.call("/artisan", { command: t, parameters: a });
+  }
+  async truncate(t = []) {
+    return await this.call("/truncate", { connections: t });
+  }
+  async factory(t, a = {}, e) {
+    return await this.call("/factory", { model: t, count: e, attrs: a });
+  }
+  async query(t, a = [], e = {}) {
+    const { connection: n = null, unprepared: r = !1 } = e;
+    if (r && a.length > 0)
+      throw new Error("Cannot use unprepared with bindings");
+    return await this.call("/query", {
+      query: t,
+      bindings: a,
+      connection: n,
+      unprepared: r
+    });
+  }
+  async select(t, a = {}, e = {}) {
+    const { connection: n = null } = e;
+    return await this.call("/select", { query: t, bindings: a, connection: n });
+  }
+  async callFunction(t, a = []) {
+    return await this.call("/function", { function: t, args: a });
+  }
+  /**
+   * Sets a laravel config value until tearDown is called (or the test ends)
+   */
+  async config(t, a) {
+    return await this.call("/dynamicConfig", { key: t, value: a });
+  }
+  /**
+   * Travel to a specific time
+   * ex: travel('2021-01-01 00:00:00')
+   */
+  async travel(t) {
+    return await this.call("/travel", { to: t });
+  }
+  async registerBootFunction(t) {
+    return await this.call("/registerBootFunction", { function: t });
+  }
+  async tearDown() {
+    return await this.call("/tearDown");
+  }
+}
+export {
+  l as Laravel,
+  u as test
+};

package/dist/laravel-playwright.umd.cjs

@@ -0,0 +1,5 @@
+(function(r,i){typeof exports=="object"&&typeof module<"u"?i(exports,require("@playwright/test")):typeof define=="function"&&define.amd?define(["exports","@playwright/test"],i):(r=typeof globalThis<"u"?globalThis:r||self,i(r.LaravelPlaywright={},r.PlaywrightTest))})(this,(function(r,i){"use strict";const u=i.test.extend({laravelBaseUrl:[void 0,{option:!0}],laravelSecret:[void 0,{option:!0}],laravel:async({laravelBaseUrl:l,laravelSecret:t,baseURL:e,request:a},s)=>{const n=l||e+"/playwright",o=new c(n,a,t);await s(o),await o.tearDown()}});class c{constructor(t,e,a=void 0){this.baseUrl=t,this.request=e,this.secret=a}async call(t,e={}){const a=this.baseUrl.replace(/\/$/,"")+t,s={Accept:"application/json"};this.secret&&(s["X-Playwright-Secret"]=this.secret);const n=await this.request.post(a,{data:e,headers:s});if(n.status()!==200)throw new Error(`
+                Failed to call Laravel ${t}.
+                Status: ${n.status()}
+                Response: ${await n.text()}
+            `);return await n.json()}async artisan(t,e=[]){return await this.call("/artisan",{command:t,parameters:e})}async truncate(t=[]){return await this.call("/truncate",{connections:t})}async factory(t,e={},a){return await this.call("/factory",{model:t,count:a,attrs:e})}async query(t,e=[],a={}){const{connection:s=null,unprepared:n=!1}=a;if(n&&e.length>0)throw new Error("Cannot use unprepared with bindings");return await this.call("/query",{query:t,bindings:e,connection:s,unprepared:n})}async select(t,e={},a={}){const{connection:s=null}=a;return await this.call("/select",{query:t,bindings:e,connection:s})}async callFunction(t,e=[]){return await this.call("/function",{function:t,args:e})}async config(t,e){return await this.call("/dynamicConfig",{key:t,value:e})}async travel(t){return await this.call("/travel",{to:t})}async registerBootFunction(t){return await this.call("/registerBootFunction",{function:t})}async tearDown(){return await this.call("/tearDown")}}r.Laravel=c,r.test=u,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@saucebase/laravel-playwright",
+  "version": "v1.0.0",
+  "description": "Blends Laravel and Playwright into seamless E2E tests — factories, queries, artisan commands, and time travel.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saucebase-dev/laravel-playwright"
+  },
+  "bugs": {
+    "url": "https://github.com/saucebase-dev/laravel-playwright/issues"
+  },
+  "homepage": "https://github.com/saucebase-dev/laravel-playwright",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && vite build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.58.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/laravel-playwright.js",
+      "require": "./dist/laravel-playwright.umd.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "vite-plugin-dts": "^4.5.4"
+  }
+}