Browser basics

A Browser wraps a page or an iframe.

Examples run inside a $this->browse() callback. Follow Laravel setup for a complete test.

Create $context with new \Puth\Context($serverUrl), then use $context->createBrowserShim() to obtain $browser. See Getting started for a complete example.

Navigate a page

$browser->visit('https://app.test');
$browser->clickLink('Settings');
$browser->waitForLocation('/settings');
$browser->assertTitleContains('Settings');

$browser->refresh() reloads the current page. $browser->back() and $browser->forward() navigate its history. Use $browser->blank() to load about:blank, or $browser->setContent(html) to replace the current document with HTML supplied by your test.

For application pages that update asynchronously, wait for the expected URL, element or text before continuing.

Inspect the URL and page

Read the current address when your test needs to use it, such as checking a redirect destination or extracting a path:

Method	Result for https://app.test:8443/orders?status=open
$browser->url()	https://app.test:8443/orders?status=open
$browser->scheme()	https
$browser->host()	app.test
$browser->path()	/orders
$browser->port()	8443

For ordinary HTTP and HTTPS URLs without an explicit port, $browser->port() returns 80 or 443. $browser->title() reads the document title and $browser->content() returns its HTML.

When you only need to check navigation, use an assertion such as $browser->assertPathIs('/orders') instead of reading and comparing the path yourself.

Set the viewport

Choose a viewport size to exercise responsive layouts:

$browser->resize(390, 844);
$browser->visit('https://app.test');
$browser->assertVisible('#mobile-menu');

$browser->viewport() reads the current viewport. $browser->maximize(), $browser->bounds(), $browser->setBounds() and $browser->move() control the browser window. These helpers operate on pages, not iframe-scoped browsers.

Work inside an iframe

$browser->withinFrame() runs a callback scoped to an iframe, then lets you continue on the outer page:

$browser->withinFrame('#checkout-frame', function ($frame) {
    $frame->click('#pay');
});
$browser->assertSee('Order');

$browser->_withinIframe() returns a separate Browser wrapper scoped to the iframe. Keep the outer Browser to continue on the page:

$frame = $browser->_withinIframe('#checkout-frame');
$frame->click('#pay');
$browser->assertSee('Order');

Evaluate JavaScript

Use $browser->evaluate() to read state that is not exposed through an existing helper. Code runs in the browser page:

$count = $browser->evaluate('document.querySelectorAll(".item").length');

Browser lifecycle

Laravel's test case creates browsers for $this->browse() callbacks and destroys the test context during teardown.

Call $browser->quit() to close its browser context. When finished with the Puth test context, call $context->destroy() to release remaining resources. Use a finally block so cleanup runs after failures too.

$browser->clone(site?, options?) creates another wrapper around the same page or a supplied page/frame. It copies timeout settings; it does not open a new page or copy custom resolver settings.