README

Laravel Playwright

A Laravel package that integrates Laravel testing functionality with Playwright. Use Laravel's powerful factories, authentication and other features directly in your Playwright tests.

Installation

Warning

ALPHA RELEASE – This package is in the alpha phase, meaning its structure may change significantly. It is recommended for internal testing and controlled environments only.

Requirements

PHP 8.2+
Laravel 11+

Via composer

composer require franbarbalopez/laravel-playwright:0.2.0-alpha --dev

Setup

After installing the package, run the installation command:

php artisan laravel-playwright:install

This will:

Install Playwright if it's not already installed
Ask for your Playwright tests directory location
Copy the necessary JavaScript helper files

Important

After installation, you must uncomment and update the baseURL in your playwright config file.

Usage

Factories

Creating Models using Factories

const user = await factory(page, {
    model: 'App\\Models\\User'
})

You may create a collection of many models using the count property:

const users = await factory(page, {
    model: 'App\\Models\\User',
    count: 3,
})

Applying States

const users = await factory(page, {
    model: 'App\\Models\\User',
    count: 5,
    states: ['suspended'],
})

Overriding Attributes

const user = await factory(page, {
    model: 'App\\Models\\User',
    attributes: {
        name: 'Abigail Otwell',
    },
})

Factory Relationships

Has Many Relationships

const user = await factory(page, {
    model: 'App\\Models\\User',
    relationships: [
        {
            method: 'has',
            name: 'posts'
            related: 'App\\Models\\Post',
            count: 3,
        }
    ]
})

You may override attributes of the related model using attributes property inside the relationship object:

const user = await factory(page, {
    model: 'App\\Models\\User',
    relationships: [
        {
            method: 'has',
            name: 'posts'
            related: 'App\\Models\\Post',
            count: 3,
            attributes: {
                title: 'New Post Title',
            }
        }
    ]
})

If you want the posts to be retrieved with the parent model you should use the load property:

const user = await factory(page, {
    model: 'App\\Models\\User',
    load: ['posts'],
    relationships: [
        {
            method: 'has',
            name: 'posts'
            related: 'App\\Models\\Post',
            count: 3,
            states: ['published'],
        }
    ]
})

Belongs To Relationships

const posts = await factory(page, {
    model: 'App\\Models\\Post',
    count: 3,
    relationships: [
        {
            method: 'for',
            name: 'user'
            related: 'App\\Models\\User',
            attributes: {
                name: 'Jessica Archer',
            }
        }
    ]
})

You could also use an id of a model generated previously:

const posts = await factory(page, {
    model: 'App\\Models\\Post',
    count: 3,
    relationships: [
        {
            method: 'for',
            name: 'user'
            related: 'App\\Models\\User',
            model_id: 1,
        }
    ]
})

Many to Many Relationships

const user = await factory(page, {
    model: 'App\\Models\\User',
    load: ['roles'],
    relationships: [
        {
            method: 'has',
            name: 'roles'
            related: 'App\\Models\\Role',
            count: 3,
        }
    ]
})

Pivot Table Attributes

const user = await factory(page, {
    model: 'App\\Models\\User',
    load: ['roles'],
    relationships: [
        {
            method: 'hasAttached',
            name: 'roles'
            related: 'App\\Models\\Role',
            count: 2,
            pivotAttributes: {
                assigned_at: '2025-03-17 18:00:00',
            },
        }
    ]
})

Polymorphic Relationships

Morph To Relationships

As in Laravel you could use here the relationships way with the for method.

Polymorphic Many to Many Relationships

You can create this relationships using the has and hasAttached methods way as if we were doing this on Laravel.

CSRF Token

const token = await csrfToken(page)

Authentication

// Login with existing user by ID
const user = await login(page, { id: 1 })

// Create and login a new user
const newUser = await login(page, {
    attributes: {
        name: 'Test User',
        email: 'test@example.com',
    }
})

// Get the current user
const currentUser = await user(page)

// Logout
await logout(page)

Artisan Commands

You can execute any Laravel Artisan command from your Playwright tests using the artisan endpoint. This is useful for resetting the database, clearing caches, or running any custom Artisan command during your end-to-end tests.

Usage Example (JavaScript)

await page.request.post('/__playwright__/artisan', {
    data: {
        command: 'migrate:fresh',
        parameters: {
            '--seed': true,
        }
    }
})

command: The Artisan command you want to run (e.g., migrate:fresh, cache:clear, route:list).
parameters: (Optional) An object with any parameters or options you want to pass to the command.

Example: List all routes in JSON format

await page.request.post('/__playwright__/artisan', {
    data: {
        command: 'route:list',
        parameters: {
            '--format': 'json'
        }
    }
})

Error Handling

If you try to run a non-existent command, the endpoint will return a 500 error.

franbarbalopez / laravel-playwright

Maintainers

Details