Pest Plugin Browser

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

2. Install Node.js dependencies:

npm install

3. 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

• back
• click
• clickAndHold
• clickAtPoint
• clickAtXPath
• clickLink
• controlClick
• doubleClick
• forward
• pause
• setTimeout
• refresh
• rightClick
• when
• screenshot
• visit
• check
• uncheck
• type
• append
• clear

Checkboxes

Check the given element.

$this->visit($url)
    ->check('#checkbox-unchecked');

Uncheck the given element.

$this->visit($url)
    ->uncheck('#checkbox-checked');

click

Click the element at the given selector.

$this->click('.selector');

clickAndHold

Perform a mouse click and hold the mouse button down at the given selector.

$this->clickAndHold('.selector');

clickAtPoint

Click the topmost element at the given pair of coordinates.

$this->clickAtPoint('//div[@class = "selector"]');

clickAtXPath

Click the element at the given XPath expression.

$this->clickAtXPath('//div[@class = "selector"]');

clickLink

Clicks some text on the page.

$this->clickLink('Sign In');

controlClick

Control click the element at the given selector.

$this->controlClick('.selector');

doubleClick

Double-click the element at the given selector.

$this->doubleClick('.selector');

Navigate back

Go back one page from the browser history.

$this->back();

Navigate forward

Go forward one page from the browser history.

$this->forward();

pause

Pauses the execution for a specified number of milliseconds.

Warning

Discouraged: Never pause in production. Tests that wait for an amount of time are inherently flaky. Use "wait for element" or "wait for an event" approaches - you can wait for an event your app dispatches.

$this->pause(5000); // Pause for 5 seconds

setTimeout

Changes the timeout for the currently running test to the given value in milliseconds. This feature works well in combination with pause when necessary or in other relevant scenarios.

$this->setTimeout(10000); // set timeout for test execution to 10 seconds

refresh

Refreshes the current page.

$this->refresh();

rightClick

Right click the element at the given selector.

$this->rightClick('.selector');

screenshot

Takes a full-page screenshot of the current page and saves it under /Browser/screenshots.

$this->screenshot('filename');

when

The when operation in Pest Browser allows you to execute different actions based on whether a specific condition is met when visiting a webpage. This feature provides dynamic test execution, enhancing the flexibility of browser tests.

$this->when(
        new Pest\Browser\Conditions\See('Laravel - The PHP Framework For Web Artisans'),
        function (Pest\Browser\PendingTest $browser): void {
            $browser->clickLink('Get Started')
                ->assertSee('Installation');
        },
        function (Pest\Browser\PendingTest $browser): void {
            $browser->assertSee('Laravel');
        }
    );

visit

Visits the given URL, and starts a new browser test.

$this->visit('https://pestphp.com');

type

Types some text into the input.

$this->type('#email', 'jane.doe@pestphp.com');

append

Appends some text to the input.

$this->append('#email', '@pestphp.com');

clear

Clears the input.

$this->clear('#email');

Available Assertions

• assertAttribute
• assertAttributeContains
• assertAttributeDoesntContain
• assertAttributeMissing
• assertDontSee
• assertHasClass
• assertQueryStringHas
• assertQueryStringMissing
• assertPathBeginsWith
• assertPathEndsWith
• assertPathContains
• assertPathIs
• assertPathIsNot
• assertPresent
• assertNotPresent
• assertScript
• assertVisible
• assertMissing
• assertChecked
• assertNotChecked
• assertInputValue
• assertInputValueIsNot

assertAttribute

Assert that the specified element has the expected attribute and value:

$this->visit($url)
    ->assertAttribute('html', 'data-theme', 'light');

assertAttributeContains

Assert that the specified element has the expected attribute and the value contains a specific value:

$this->visit($url)
    ->assertAttributeContains('html', 'data-theme', 'ight');

assertAttributeDoesntContain

Assert that the specified element has the expected attribute, but the value does not contain a specific value:

$this->visit($url)
    ->assertAttributeDoesntContain('html', 'data-theme', 'not here');

assertAttributeMissing

Assert that the specified element is missing a particular attribute :

$this->visit($url)
    ->assertAttributeMissing('html', 'data-missing');

assertDontSee

Assert that the given text is not present on the page:

$this->visit($url)
    ->assertDontSee('we are a streaming service');

assertHasClass

Assert that the element has css classes bases upon string, array, regex

Given the html

<section>
    <div id="div-1" class="class-1"></div>
    <div id="div-2" class="class-1 class-2"></div>
    <div id="div-3" class="class-1 selected class-3"></div>
    <ul>
        <li class="component"></li>
        <li class="component selected"></li>
        <li class="component"></li>
    </ul>
</section>

$this->visit('/test/interactive-elements')
    ->assertHasClass('#div-1', 'class-1');

$this->visit('/test/interactive-elements')
    ->assertHasClass('#div-3', 'class-1 selected class-3');

$this->visit('/test/interactive-elements')
    ->assertHasClass('#div-3', '/(^|\s)selected(\s|$)/');

$this->visit('/test/interactive-elements')
    ->assertHasClass('ul > .component', ['component', 'component selected', 'component']);

assertVisible

Assert that an element with the given selector is visible:

test('assert visible', function () {
    $this->visit($url)
        ->assertVisible('h1:visible');
});

assertMissing

Assert that an element with the given selector is hidden:

test('assert missing', function () {
    $this->visit($url)
        ->assertMissing('a.hidden');

assertQueryStringHas

Assert that the given query string is present in the url:

$this->visit($url)
    ->assertQueryStringHas('q', 'test');

assertQueryStringMissing

Assert that the given query string is not present in the url:

$this->visit($url)
    ->assertQueryStringMissing('q', 'test-1');

assertPathBeginsWith

Assert that the current URL path begins with the given path:

$this->visit($url)
    ->assertPathBeginsWith('/test');

assertPathEndsWith

Assert that the current URL path ends with the given path:

$this->visit($url)
    ->assertPathEndsWith('/test');

assertPathContains

Assert that the current URL path contains the given path:

$this->visit($url)
    ->assertPathContains('/test');

assertPathIs

Assert that the current URL path matches the given path:

$this->visit($url)
    ->assertPathIs('/test');

// Asterisk (*) can be used as a wildcard

$this->visit($url)
    ->assertPathIs('/test/*');

assertPathIsNot

Assert that the current URL path does not match the given path:

$this->visit($url)
    ->assertPathIsNot('/test');

assertScript

Assert that the given script returns the expected value:

$this->visit($url)
    ->assertScript('document.querySelector("title").textContent.includes("Laravel")', true);

assertPresent

Assert that the element with a given selector is present on the page:

$this->visit($url)
    ->assertPresent('h1:visible');

assertNotPresent

Assert that the element with a given selector is not present on the page:

$this->visit($url)
    ->assertNotPresent('a.non-existing-class');

assertChecked

Assert that the element with a given selector is checked:

$this->visit($url)
    ->assertChecked('input[type="checkbox"].checked');

assertNotChecked

Assert that the element with a given selector is not checked:

$this->visit($url)
    ->assertNotChecked('input[type="checkbox"].checked');

assertInputValue

Assert that the value of the input with the given selector is the expected value:

$this->visit($url)
    ->assertInputValue('#email', 'jane.doe@pestphp.com');

assertInputValueIsNot

Assert that the value of the input with the given selector is not the expected value:

$this->visit($url)
    ->assertInputValueIsNot('#email', 'jane.doe@pestphp.com');