Pest Plugin POM

A Pest plugin for writing browser tests using the Page Object Model pattern. Integrates with pest-plugin-browser.

Early Release: Pre-v1, bugs are expected. Please open an issue if you find one.

Requirements

• PHP ^8.3
• Pest ^4.0
• pest-plugin-browser ^4.0

Installation

composer require thelemon2020/pest-plugin-pom --dev

Config

php artisan vendor:publish --tag=pest-plugin-pom-config

Creates config/pest-plugin-pom.php:

return [
    'path' => 'tests/Browser/Pages',
];

Page Objects

Extend Page, define a url(), and add interaction methods:

namespace Tests\Browser\Pages;

use Thelemon2020\PestPom\Page;
use Thelemon2020\PestPom\Concerns\InteractsWithForms;

class LoginPage extends Page
{
    use InteractsWithForms;

    public static function url(): string
    {
        return '/login';
    }

    public function loginAs(string $email, string $password): static
    {
        return $this
            ->fillForm(['Email' => $email, 'Password' => $password])
            ->submitForm('Log in');
    }
}

Navigate to a page with page() or ::open():

$page = page(LoginPage::class);
// or
$page = LoginPage::open();

Parameterized URLs

class ProductPage extends Page
{
    public static function url(): string
    {
        return '/products/{id}';
    }
}

ProductPage::open(['id' => 42]);
$page->navigateTo(ProductPage::class, ['id' => 42]);

Navigating Between Pages

navigateTo() sends the browser to a page's URL. nowOn() re-wraps the current session as a different page type without reloading — useful after a server-side redirect. nowOn() also verifies the current URL matches the destination.

// explicit navigation
$page->navigateTo(DashboardPage::class);

// after a redirect
$page->submitForm('Log in')->nowOn(DashboardPage::class);

Tests

Tests using Page Objects live in tests/Browser/ — Pest's browser plugin handles the rest.

it('allows a user to log in', function () {
    page(LoginPage::class)
        ->loginAs('jane@example.com', 'password')
        ->assertSee('Dashboard');
});

Components

Components encapsulate a reusable piece of UI. They work like pages but have no URL and are always obtained through a page instance.

php artisan pest:component SearchBar

namespace Tests\Browser\Components;

use Thelemon2020\PestPom\Component;

class SearchBarComponent extends Component
{
    public static function selector(): string
    {
        return '#search-bar';
    }

    public function search(string $query): static
    {
        return $this
            ->fill('input[name=query]', $query)
            ->click('button[type=submit]');
    }
}

page(DashboardPage::class)
    ->component(SearchBarComponent::class)
    ->search('pest php')
    ->assertSee('pest-plugin-browser');

Selectors passed to interaction methods are scoped to the component's root element automatically.

Selector types

selector() supports all Pest selector forms:

Tip: If a text content selector isn't behaving as expected, use Playwright's explicit text= prefix — e.g. 'text=submit'.

Typed Accessors

class DashboardPage extends Page
{
    public function searchBar(): SearchBarComponent
    {
        return $this->component(SearchBarComponent::class);
    }
}

Multiple Instances

Use components()->item(n) (1-based) to target a specific occurrence:

$page->components(CardComponent::class)->assertTotal(3);
$page->components(CardComponent::class)->item(2)->assertTitle('Advanced Usage');

Sub-Components

Call component() on a component to create a child scoped within the parent:

// resolves to: #nav .user-menu
$page->header()->userMenu()->assertSee('Jane Doe');

Scoped Assertions

Scoped Interactions

press(), pressAndWaitFor(), and withKeyDown() are not scoped — they pass through via __call.

Generators

php artisan pest:page Login
php artisan pest:page Register --concerns=forms,alerts

php artisan pest:component SearchBar
php artisan pest:component DataTable --concerns=navigation,modals

Available concerns: forms, alerts, modals, navigation.

The Page/Component suffix is optional and won't be doubled.

Concerns

InteractsWithForms

InteractsWithAlerts

InteractsWithModals

InteractsWithNavigation

Expectations

expect($page)->toBeOnPage(DashboardPage::class);
expect($page)->toSee('Welcome back');

License

MIT