pestphp/pest-plugin-browser

Pest plugin to test browser interactions

4.x-dev 2025-06-15 01:29 UTC

Requires

• php: ^8.3
• pestphp/pest: ^4.0.0
• pestphp/pest-plugin: ^4.0.0
• phrity/websocket: ^3.5.0
• symfony/process: ^7.3.0

Requires (Dev)

• ext-pcntl: *
• ext-posix: *
• fakerphp/faker: ^1.24.1
• laravel/framework: ^11.45.1
• laravel/pail: ^1.2.3
• laravel/pint: ^1.22.1
• laravel/sail: ^1.43.1
• laravel/tinker: ^2.10.1
• livewire/livewire: ^3.6.3
• mockery/mockery: ^1.6.12
• nunomaduro/collision: ^8.8.1
• peckphp/peck: ^0.1.3
• pestphp/pest-dev-tools: ^4.0.0
• pestphp/pest-plugin-laravel: ^4.0
• pestphp/pest-plugin-type-coverage: ^4.0.0

MIT

• framework
• php
• testing
• test
• browser
• unit
• pest

README

This repository contains the Pest Plugin Browser.

If you want to start testing your application with Pest, visit the main Pest Repository.

Community & Resources

• Explore our docs at pestphp.com »
• Follow us on Twitter at @pestphp »
• Join us at discord.gg/kaHY6p54JH » or t.me/+kYH5G4d5MV83ODk0 »
• Follow the creator Nuno Maduro:
  • YouTube: youtube.com/@nunomaduro — Videos every weekday
  • Twitch: twitch.tv/enunomaduro — Streams (almost) every weekday
  • Twitter / X: x.com/enunomaduro
  • LinkedIn: linkedin.com/in/nunomaduro
  • Instagram: instagram.com/enunomaduro
  • Tiktok: tiktok.com/@enunomaduro

Installation (for development purposes)

1. Install PHP dependencies using Composer:

composer install

1. Install Node.js dependencies:

npm install

1. Install Playwright browsers:

npx playwright install

Running Tests

To run the test suite, execute:

./vendor/bin/pest

The Playground

For each Operation/Assertion, we add a corresponding Test.

We can make use of the playground()->url() helper, to get its URL during the test.

We can provide a URI that will be appended, e.g: playground()->url('/test/interactive-elements').

$this->visit(playground()->url('/test/interactive-elements'))
    ->assertUrlIs(playground()->url('/test/interactive-elements'))

Routes and views for testing

Check the playground/resources/views/test-pages folder for existing views.

They are accessible by the playground route /test/{page}.

E.g.: The view resources/views/test-pages/interactive-elements.blade.php is visited on playground()->url('/test/interactive-elements').

The playground is standard Laravel App, where you may add a page with a feature for your test.

Just add the view, and the Nav Menu will automatically update based on the view name.

License

Pest is an open-sourced software licensed under the MIT license.

Documentation

Pest Plugin Browser brings end-to-end testing to the elegant syntax from Pest. This allows to test your application in a browser environment, enabling to test all the components, such as frontend, backend and database.

Installation

TBD

Available Operations

• url
• goto
• title
• getAttribute
• querySelector / querySelectorAll
• locator
• getByRole
• getByTestId
• getByAltText
• getByLabel
• getByPlaceholder
• getByText
• getByTitle
• content
• isEnabled
• isVisible
• isHidden
• isEditable
• isDisabled
• isChecked
• fill
• innerText
• textContent
• inputValue
• check
• uncheck
• hover
• focus
• press
• type
• waitForLoadState
• waitForURL
• waitForSelector
• dragAndDrop
• setContent
• selectOption
• evaluate
• evaluateHandle
• forward
• back
• reload
• screenshot
• locator.click
• locator.fill
• locator.type
• locator.press
• locator.check
• locator.uncheck
• locator.isVisible
• locator.isHidden
• locator.isEnabled
• locator.isDisabled
• locator.isEditable
• locator.isChecked
• locator.textContent
• locator.innerText
• locator.inputValue
• locator.getAttribute
• locator.screenshot

url

Get the current URL of the page.

$page = page('/test/frame-tests');
$currentUrl = $page->url();

goto

Navigate to a given URL.

$page = page('/test/frame-tests');
$page->goto('https://example.com');

title

Get the meta title of the page.

$page = page('/test/frame-tests');
$title = $page->title();

getAttribute

Get the value of an attribute for a selector.

$page = page('/test/frame-tests');
$id = $page->getAttribute('h1', 'id');

querySelector / querySelectorAll

Find elements by selector.

$page = page('/test/frame-tests');
$element = $page->querySelector('h1');
$elements = $page->querySelectorAll('div');

locator

Create a locator for a selector.

$page = page('/test/frame-tests');
$locator = $page->locator('button.submit');

getByRole

Create a locator by ARIA role.

$page = page('/test/frame-tests');
$button = $page->getByRole('button');

getByTestId

Create a locator by test id.

$page = page('/test/frame-tests');
$testElement = $page->getByTestId('login-form');

getByAltText

Create a locator by alt text.

$page = page('/test/frame-tests');
$image = $page->getByAltText('Logo');

getByLabel

Create a locator by label text.

$page = page('/test/frame-tests');
$input = $page->getByLabel('Email');

getByPlaceholder

Create a locator by placeholder text.

$page = page('/test/frame-tests');
$input = $page->getByPlaceholder('Enter your email');

getByText

Create a locator by text content.

$page = page('/test/frame-tests');
$link = $page->getByText('Sign In');

getByTitle

Create a locator by title attribute.

$page = page('/test/frame-tests');
$element = $page->getByTitle('Main Section');

content

Get the full HTML contents of the page.

$page = page('/test/frame-tests');
$html = $page->content();

isEnabled

Check if an element is enabled.

$page = page('/test/frame-tests');
$isEnabled = $page->isEnabled('button.submit');

isVisible

Check if an element is visible.

$page = page('/test/frame-tests');
$isVisible = $page->isVisible('h1');

isHidden

Check if an element is hidden.

$page = page('/test/frame-tests');
$isHidden = $page->isHidden('h1');

isEditable

Check if an element is editable.

$page = page('/test/frame-tests');
$isEditable = $page->isEditable('input[type="text"]');

isDisabled

Check if an element is disabled.

$page = page('/test/frame-tests');
$isDisabled = $page->isDisabled('button.submit');

isChecked

Check if a checkbox or radio is checked.

$page = page('/test/frame-tests');
$isChecked = $page->isChecked('input[type="checkbox"]');

fill

Fill a form field.

$page = page('/test/frame-tests');
$page->fill('input[name="email"]', '[e-mail]');

innerText

Get the inner text of an element.

$page = page('/test/frame-tests');
$text = $page->innerText('h1');

textContent

Get the text content of an element.

$page = page('/test/frame-tests');
$content = $page->textContent('h1');

inputValue

Get the value of an input element.

$page = page('/test/frame-tests');
$value = $page->inputValue('input[name="email"]');

check

Check a checkbox or radio button.

$page = page('/test/frame-tests');
$page->check('input[type="checkbox"]');

uncheck

Uncheck a checkbox or radio button.

$page = page('/test/frame-tests');
$page->uncheck('input[type="checkbox"]');

hover

Hover over an element.

$page = page('/test/frame-tests');
$page->hover('button');

focus

Focus an element.

$page = page('/test/frame-tests');
$page->focus('input[name="email"]');

press

Press a key on an element.

$page = page('/test/frame-tests');
$page->press('input[name="email"]', 'Enter');

type

Type text into an element.

$page = page('/test/frame-tests');
$page->type('input[name="email"]', 'hello world');

waitForLoadState

Wait for the page to reach a certain load state.

$page = page('/test/frame-tests');
$page->waitForLoadState('networkidle');

waitForURL

Wait for the page to reach a certain URL.

$page = page('/test/frame-tests');
$page->waitForURL('https://example.com/next');

waitForSelector

Wait for a selector to appear or reach a state.

$page = page('/test/frame-tests');
$page->waitForSelector('h1');

dragAndDrop

Drag one element to another.

$page = page('/test/frame-tests');
$page->dragAndDrop('#source', '#target');

setContent

Set the HTML content of the page.

$page = page('/test/frame-tests');
$page->setContent('<h1>Hello</h1>');

selectOption

Select options in a <select> element.

$page = page('/test/frame-tests');
$page->selectOption('select[name="country"]', 'US');

evaluate

Run JavaScript in the page context.

$page = page('/test/frame-tests');
$result = $page->evaluate('() => document.title');

evaluateHandle

Run JavaScript and return a handle.

$page = page('/test/frame-tests');
$handle = $page->evaluateHandle('() => window');

forward

Navigate forward in browser history.

$page = page('/test/frame-tests');
$page->forward();

back

Navigate back in browser history.

$page = page('/test/frame-tests');
$page->back();

reload

Reload the current page.

$page = page('/test/frame-tests');
$page->reload();

screenshot

Take a screenshot of the page.

$page = page('/test/frame-tests');
$page->screenshot('example.png');

locator.click

Click the element found by the locator.

$locator = $page->locator('button.submit');
$locator->click();

locator.fill

Fill an input or textarea found by the locator.

$locator = $page->locator('input[name="email"]');
$locator->fill('[e-mail]');

locator.type

Type text into the element found by the locator.

$locator = $page->locator('input[name="email"]');
$locator->type('hello world');

locator.press

Press a key on the element found by the locator.

$locator = $page->locator('input[name="email"]');
$locator->press('Enter');

locator.check

Check a checkbox or radio button found by the locator.

$locator = $page->locator('input[type="checkbox"]');
$locator->check();

locator.uncheck

Uncheck a checkbox or radio button found by the locator.

$locator = $page->locator('input[type="checkbox"]');
$locator->uncheck();

locator.isVisible

Check if the element found by the locator is visible.

$locator = $page->locator('h1');
$isVisible = $locator->isVisible();

locator.isHidden

Check if the element found by the locator is hidden.

$locator = $page->locator('h1');
$isHidden = $locator->isHidden();

locator.isEnabled

Check if the element found by the locator is enabled.

$locator = $page->locator('button.submit');
$isEnabled = $locator->isEnabled();

locator.isDisabled

Check if the element found by the locator is disabled.

$locator = $page->locator('button.submit');
$isDisabled = $locator->isDisabled();

locator.isEditable

Check if the element found by the locator is editable.

$locator = $page->locator('input[type="text"]');
$isEditable = $locator->isEditable();

locator.isChecked

Check if a checkbox or radio button found by the locator is checked.

$locator = $page->locator('input[type="checkbox"]');
$isChecked = $locator->isChecked();

locator.textContent

Get the text content of the element found by the locator.

$locator = $page->locator('h1');
$content = $locator->textContent();

locator.innerText

Get the inner text of the element found by the locator.

$locator = $page->locator('h1');
$text = $locator->innerText();

locator.inputValue

Get the value of an input element found by the locator.

$locator = $page->locator('input[name="email"]');
$value = $locator->inputValue();

locator.getAttribute

Get an attribute value from the element found by the locator.

$locator = $page->locator('h1');
$id = $locator->getAttribute('id');

locator.screenshot

Take a screenshot of the element found by the locator.

$locator = $page->locator('h1');
$locator->screenshot('element.png');

Available Expectations

toHaveTitle

Checks that the page has the given title.

expect($page)->toHaveTitle('My Page Title');

toBeChecked

Checks that the locator is checked (for checkboxes/radios).

expect($locator)->toBeChecked();

toBeVisible

Checks that the locator is visible on the page.

expect($locator)->toBeVisible();

toBeEnabled

Checks that the locator is enabled (not disabled).

expect($locator)->toBeEnabled();

toBeDisabled

Checks that the locator is disabled.

expect($locator)->toBeDisabled();

toBeEditable

Checks that the locator is editable (input, textarea, etc.).

expect($locator)->toBeEditable();

toBeHidden

Checks that the locator is hidden from view.

expect($locator)->toBeHidden();

toHaveId

Checks that the locator has the given id attribute.

expect($locator)->toHaveId('element-id');

toHaveClass

Checks that the locator has the given class attribute.

expect($locator)->toHaveClass('class-name');

toHaveRole

Checks that the locator has the given ARIA role.

expect($locator)->toHaveRole('button');

toBeEmpty

Checks that the locator's text content is empty.

expect($locator)->toBeEmpty();

toHaveValue

Checks that the locator has a value (for input elements).

expect($locator)->toHaveValue('expected-value');

toHaveScreenshot

The toHaveScreenshot expectation takes a screenshot of the current page and saves it to the specified path. It then checks that the screenshot file exists at that path. This is useful for verifying that screenshots are being generated correctly during browser tests.

Usage:

$page = page('/test/frame-tests');
$screenshotName = 'screenshot.png';
expect($page)->toHaveScreenshot($screenshotName);
expect(file_exists(\Pest\Browser\Support\Screenshot::path($screenshotName)))->toBeTrue();

If the screenshot cannot be saved (e.g., due to an invalid or unwritable path), the expectation will fail and throw an exception.

$page = page('/test/frame-tests');
$invalidPath = '/invalid-dir/not-the-screenshot.png';
expect($page)->toHaveScreenshot($invalidPath); // This will throw an exception

toHaveText

Checks that the locator contains the given text content.

expect($locator)->toHaveText('expected text');