Laravel Dusk

https://github.com/laravel/dusk
Admin
Laravel Dusk provides an expressive, easy-to-use browser automation and end-to-end testing API for...
Tokens:118,087
Snippets:922
Trust Score:9.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### SupportsChrome trait usage in DuskTestCase::prepare()

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-process.md

Shows two examples of the prepare() method in DuskTestCase. The first starts the Chromedriver with a port argument unless running in Sail. The second uses a custom binary path via useChromedriver() before starting the driver.

```php
// In DuskTestCase::prepare() (from the scaffold):
#[BeforeClass]
public static function prepare(): void
{
    if (! static::runningInSail()) {
        static::startChromeDriver(['--port=9515']);
    }
}

// Custom binary:
public static function prepare(): void
{
    static::useChromedriver(base_path('bin/my-chromedriver'));
    static::startChromeDriver(['--port=9515']);
}
```

--------------------------------

### responsiveScreenshots usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Example call to responsiveScreenshots with 'welcome'. Produces welcome-xs.png through welcome-2xl.png for each responsive screen size.

```php
$browser->responsiveScreenshots('welcome');
// produces welcome-xs.png ... welcome-2xl.png
```

--------------------------------

### visitRoute usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Example of calling visitRoute with a named route and parameters.

```php
$browser->visitRoute('users.show', ['user' => 1]);
```

--------------------------------

### pointer motion usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-mouse.md

Example of using moveMouse and mouseover to move the mouse and hover over an element.

```php
$browser->moveMouse(10, 10)->mouseover('#nav')...;
```

--------------------------------

### resize() usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Example call to resize the browser window to 1024x768 pixels.

```php
$browser->resize(1024, 768);
```

--------------------------------

### setUp() method signature

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/test-case.md

Protected lifecycle method that registers default Browser static configuration.

```php
protected function setUp(): void
```

--------------------------------

### click usage examples

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-mouse.md

Examples of using click with a selector and without a selector to click at the current position.

```php
$browser->click('#submit');
$browser->click(); // click at current position
```

--------------------------------

### Example usage of value and attribute assertions

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-assertions-forms.md

Shows a chained example using assertValue, assertAttribute, assertDataAttribute, assertAriaAttribute, and assertAttributeMissing on a browser instance. This demonstrates how to verify element values and attributes in a single fluent call.

```php
$browser->assertValue('input[name=q]', 'laravel')
        ->assertAttribute('#card', 'data-id', '7')
        ->assertDataAttribute('#card', 'action', 'edit')
        ->assertAriaAttribute('#menu', 'expanded', 'true')
        ->assertAttributeMissing('#card', 'hidden');
```

--------------------------------

### on method usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Example of calling on with a LoginPage object, which also runs assertions.

```php
$browser->on(new LoginPage); // also asserts
```

--------------------------------

### Usage examples for dusk:chrome-driver

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-driver-command.md

Common invocations: latest stable, detect installed Chrome, specify a major version, exact legacy version, all OS binaries, and proxy with SSL verification bypass.

```bash
php artisan dusk:chrome-driver                 # latest stable
php artisan dusk:chrome-driver --detect        # match installed Chrome
php artisan dusk:chrome-driver 117             # Chrome 117 major
php artisan dusk:chrome-driver 2.44            # exact legacy version
php artisan dusk:chrome-driver --all           # all OS binaries
php artisan dusk:chrome-driver --proxy=tcp://127.0.0.1:9000 --ssl-no-verify
```

--------------------------------

### Path assertions example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-url-assertions.md

Chained assertions for path beginning and exact path match.

```php
$browser->assertPathBeginsWith('/docs')->assertPathIs('/docs/dusk');
```

--------------------------------

### Example HTTP request and response for GET /_dusk/user

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/endpoints.md

Shows the expected HTTP interaction with the endpoint. When a user is authenticated, the response is a JSON object with `id` and `className`. When no user is authenticated (guest), the response is an empty JSON array `[]`.

```http
GET /_dusk/user
→ 200 application/json: {"id":1,"className":"App\\Models\\User"}

GET /_dusk/user (guest)
→ 200 application/json: []
```

--------------------------------

### withKeyboard usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Shows using withKeyboard() to press a key, type text, and release a key via the Keyboard instance.

```php
$browser->withKeyboard(function ($keyboard) {
    $keyboard->press('{shift}')->type('Hello')->release('{shift}');
});
```

--------------------------------

### dusk:install command usage

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/console-generators.md

Basic and proxy usage of the dusk:install command. The --proxy option specifies a proxy for the ChromeDriver download, and --ssl-no-verify bypasses SSL verification.

```bash
php artisan dusk:install
php artisan dusk:install --proxy=tor://127.0.0.1:9050
```

--------------------------------

### Example Navbar component and usage

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/component.md

Complete example of a Navbar component extending the base Component class, defining selector, assert, elements, and a custom openAccount method. The usage block shows how to use the component inside a with() scope, where the component's assertions run and its shortcuts and step methods apply.

```php
namespace Tests\Browser\Components;

use Laravel\Dusk\Browser;
use Laravel\Dusk\Component as BaseComponent;

class Navbar extends BaseComponent
{
    public function selector(): string
    {
        return 'nav.main';
    }

    public function assert(Browser $browser): void
    {
        $browser->assertVisible('@brand');
    }

    public function elements(): array
    {
        return [
            '@brand' => '.brand',
            '@account' => '.account-link',
        ];
    }

    public function openAccount(Browser $browser): void
    {
        $browser->click('@account');
    }
}
```

```php
$browser->with(new Navbar, function ($navbar) {
    $navbar->assertSee('Laravel')->openAccount();
});
```

--------------------------------

### Optional config/dusk.php example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/configuration.md

Optional configuration file (not shipped) showing the `dusk.path`, `dusk.domain`, and `dusk.middleware` keys. The `domain` key, when non-null, makes `Browser::loginAs()`/`logout()` build absolute route URLs.

```php
// config/dusk.php (optional, not shipped)
return [
    'path' => '_dusk',
    'domain' => 'testing.example.com',
    'middleware' => ['web'],
];
```

--------------------------------

### Usage example for pageElements and format

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/element-resolver.md

Shows how to set element shortcuts and format selectors. The first format call uses the shortcut, the second falls back to the Dusk attribute selector.

```php
$resolver->pageElements(['@submit' => 'button.primary']);
$resolver->format('@submit');   // "body button.primary"
$resolver->format('@login');    // "body [dusk=\"login\"]"
```

--------------------------------

### waitForEvent Usage Example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-waits.md

Example of waiting for a 'transitionend' event on the '#modal' element after clicking '#show'.

```php
$browser->click('#show')->waitForEvent('transitionend', '#modal');
```

--------------------------------

### storeConsoleLog usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Example call to storeConsoleLog with 'home'. Only runs for browsers in Browser::$supportsRemoteLogs (CHROME, PHANTOMJS). Writes pretty-printed JSON to {storeConsoleLogAt}/{name}.log if any entries survive filtering.

```php
$browser->storeConsoleLog('home');
```

--------------------------------

### dusk:chrome-driver {version?}

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-driver-command.md

Downloads the correct ChromeDriver binary into `dusk/bin/`. Accepts an optional version argument and various options to control the installation.

```APIDOC
## [CONSOLE] dusk:chrome-driver

### Description
Downloads the correct ChromeDriver binary into `dusk/bin/`. The version can be specified as an argument or detected automatically.

### Method
Console command (Artisan)

### Endpoint
`php artisan dusk:chrome-driver {version?}`

### Parameters
#### Arguments
- **version** (string|null) - Optional - Exact version, Chrome major version, or omitted for latest stable.

#### Options
- **--all** (bool) - Optional - Install a ChromeDriver binary for every OS.
- **--detect** (bool) - Optional - Detect the installed Chrome / Chromium version.
- **--proxy** (string|null) - Optional - The proxy to download the binary through (example: "tcp://127.0.0.1:9000").
- **--ssl-no-verify** (bool) - Optional - Bypass SSL certificate verification when installing through a proxy.

### Request Example
```bash
php artisan dusk:chrome-driver                 # latest stable
php artisan dusk:chrome-driver --detect        # match installed Chrome
php artisan dusk:chrome-driver 117             # Chrome 117 major
php artisan dusk:chrome-driver 2.44            # exact legacy version
php artisan dusk:chrome-driver --all           # all OS binaries
php artisan dusk:chrome-driver --proxy=tcp://127.0.0.1:9000 --ssl-no-verify
```

### Response
#### Success Response
- Prints `ChromeDriver binaries successfully installed for version X.` or similar.

#### Error Handling
- Throws `\Exception` on unresolvable version, failed download, failed extraction, missing milestone entry, or unreadable URLs.

```

--------------------------------

### visit method usage examples

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Examples of calling visit with a relative URL, an absolute URL, and a Page object. When a Page is passed, its url() method is used and on($page) is invoked.

```php
$browser->visit('/login');
$browser->visit('https://example.com');
$browser->visit(new LoginPage);
```

--------------------------------

### assertRouteIs usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-url-assertions.md

Example of asserting the current URL matches a named route with parameters.

```php
$browser->assertRouteIs('users.show', ['user' => 1]);
```

--------------------------------

### assertUrlIs usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-url-assertions.md

Example of asserting the current URL matches a pattern with a wildcard.

```php
$browser->assertUrlIs('https://laravel.com/docs/*');
```

--------------------------------

### Scheme, host, port assertions example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-url-assertions.md

Chained assertions for scheme, host, and port using regex matching.

```php
$browser->assertSchemeIs('https')->assertHostIs('laravel.com')->assertPortIs('443');
```

--------------------------------

### assertCount and assertScript usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-assertions.md

Example showing how to assert an element count and a JavaScript expression result in a single browser chain.

```php
$browser->assertCount('.item', 3)
        ->assertScript('document.querySelectorAll(".item").length', 3);
```

--------------------------------

### click variants usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-mouse.md

Chained example using clickAtPoint, clickAtXPath, doubleClick, rightClick, and controlClick.

```php
$browser->clickAtPoint(50, 50)
        ->clickAtXPath("//button[contains(text(), 'Go')]")
        ->doubleClick('#row')
        ->rightClick('#row')
        ->controlClick('a[target=_blank]');
```

--------------------------------

### Example usage of browse() with one and two browsers

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/test-case.md

Shows how to use browse() with a single browser to visit a page and assert content, and with two browsers to simulate chat interaction. The first browser logs in as user 1, the second as user 2, and they exchange a message.

```php
public function test_orders_page(): void
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/orders')->assertSee('Orders');
    });

    // two browsers interact:
    $this->browse(function (Browser $first, Browser $second) {
        $first->loginAs(1)->visit('/chat');
        $second->loginAs(2)->visit('/chat');
        $first->type('message', 'hi')->press('Send');
        $second->assertSee('hi');
    });
}
```

--------------------------------

### Install Chrome Driver for Dusk 7.0

Source: https://github.com/laravel/dusk/blob/8.x/UPGRADE.md

Use this command to install the required Chrome driver for your operating system, as Dusk no longer ships with pre-installed Chrome binaries.

```zsh
php artisan dusk:chrome-driver
```

--------------------------------

### dump() and dd() usage examples

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Shows how to use dump() to print HTML and continue, and dd() to print HTML, quit, and stop.

```php
$browser->visit('/')->dump();      // prints HTML, continues
$browser->visit('/')->dd();        // prints HTML, quits, stops
```

--------------------------------

### Pause methods usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-scoping.md

Example of using `pause` and `pauseIf` to control execution timing. `pause` sleeps for the given milliseconds, `pauseIf` pauses only when the condition is truthy.

```php
$browser->pause(250)->assertSee('Loaded');
$browser->pauseIf($userIsAdmin, 400);
```

--------------------------------

### storeSource usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Calls storeSource with 'home' to save the current page source to a file named 'home.txt' in the configured directory.

```php
$browser->storeSource('home');
```

--------------------------------

### Example LoginPage class

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/page.md

Complete example of a page object extending Laravel\Dusk\Page. It defines url(), assert(), elements(), and a custom login() method that becomes callable on the browser chain via Browser::__call().

```php
namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;
use Laravel\Dusk\Page as BasePage;

class LoginPage extends BasePage
{
    public function url(): string
    {
        return '/login';
    }

    public function assert(Browser $browser): void
    {
        $browser->assertPathIs('/login');
    }

    public function elements(): array
    {
        return [
            '@email' => 'input[name=email]',
            '@submit' => 'button[type=submit]',
        ];
    }

    public function login(Browser $browser, string $email): void
    {
        $browser->type('email', $email)->press('@submit');
    }
}
```

--------------------------------

### Chaining wait methods example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-waits.md

Example of chaining multiple wait methods to wait for an element, text, text in a selector, attribute value, link, and element absence. Each method uses default timeouts unless specified.

```php
$browser->waitFor('#modal')
        ->waitForText('Order complete', 10)
        ->waitForTextIn('.status', 'sent')
        ->waitForAttributeIn('#btn', 'disabled', 'true', 8)
        ->waitForLink('Read more')
        ->waitUntilMissing('#spinner');
```

--------------------------------

### screenshot() usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Takes a screenshot named 'homepage'.

```php
$browser->screenshot('homepage');
```

--------------------------------

### Handling unknown keyboard methods

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/keyboard.md

Example of catching a BadMethodCallException when calling an undefined keyboard method.

```php
try {
    $keyboard->methodThatDoesNotExist();
} catch (\BadMethodCallException $e) {
    // "Call to undefined keyboard method [methodThatDoesNotExist]."
}
```

--------------------------------

### Wait for Dialog and Reload Examples

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-waits.md

Shows usage of waitForDialog, clickAndWaitForReload, and waitForReload. Note that waitForReload requires a callback when you don't click yourself; passing none simply waits for any reload.

```php
$browser->waitForDialog()->acceptDialog();                          // no callback
$browser->clickAndWaitForReload('#submit');                          // click that triggers reload
$browser->waitForReload(fn ($b) => $b->press('Save'));               // explicit callback
```

--------------------------------

### script() method signature and usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Executes one or more JavaScript snippets via driver->executeScript(). Returns an array keyed by input order.

```php
public function script($scripts)
```

```php
$counts = $browser->script([
    'return document.querySelectorAll("a").length;',
    'return document.title;',
]);
```

--------------------------------

### Fragment assertions example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-url-assertions.md

Chained assertions for fragment matching and beginning with.

```php
$browser->assertFragmentIs('results')->click('#next')->assertFragmentBeginsWith('results');
```

--------------------------------

### dusk:make, dusk:page, dusk:component command usage

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/console-generators.md

Examples of generating a Dusk test class, a page class, and a component class. The name argument can include slashes to specify subdirectories.

```bash
php artisan dusk:make LoginTest
php artisan dusk:page Admin/Dashboard
php artisan dusk:component Navbar
```

--------------------------------

### Usage examples for dusk and dusk:fails

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/console-commands.md

Shows common invocations of the 'dusk' and 'dusk:fails' Artisan commands. The '--browse' option opens a real browser, '--filter' passes through to PHPUnit, and '--pest' is specific to 'dusk:fails'.

```bash
php artisan dusk
php artisan dusk --browse
php artisan dusk --filter=test_orders
php artisan dusk:fails --pest
```

--------------------------------

### screenshotElement usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Example call to screenshotElement with '#card' and 'card'. Scrolls the element into view and captures it via WebDriver's takeElementScreenshot().

```php
$browser->screenshotElement('#card', 'card');
```

--------------------------------

### JavaScript dialog usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Demonstrates accepting a dialog after a click and typing a value into a prompt before accepting. acceptDialog() accepts the open alert/confirm, typeInDialog() sends keys to an open prompt.

```php
$browser->click('#delete')->acceptDialog();
$browser->typeInDialog('yes')->acceptDialog();
```

--------------------------------

### SupportsChrome::startChromeDriver

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-process.md

Starts the Chromedriver process and registers an afterClass callback to stop it automatically.

```APIDOC
## SupportsChrome::startChromeDriver

### Description
Builds the Chromedriver process, starts it, and registers stopChromeDriver() as an afterClass callback for automatic teardown.

### Method
startChromeDriver

### Signature
```php
public static function startChromeDriver(array $arguments = [])
```

### Parameters
- **$arguments** (array) - Optional - Extra Chromedriver CLI arguments. Defaults to [].

### Exceptions
- **\RuntimeException** - If the Chromedriver binary path is invalid.

### Example
```php
// In DuskTestCase::prepare()
#[BeforeClass]
public static function prepare(): void
{
    if (! static::runningInSail()) {
        static::startChromeDriver(['--port=9515']);
    }
}
```
```

--------------------------------

### ChromeProcess::toProcess() usage

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-process.md

Creates a ChromeProcess instance and calls toProcess() with extra Chromedriver arguments, then starts the process. The process runs the resolved Chromedriver binary with the given arguments and environment DISPLAY on non-mac/Windows systems.

```php
use Laravel\Dusk\Chrome\ChromeProcess;

$process = (new ChromeProcess)->toProcess(['--port=9515', '--url-base=/']);
$process->start();
```

--------------------------------

### tap() method signature and usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Runs a callback with the browser instance, returns $this for chaining. The callback receives $this and its return value is ignored.

```php
public function tap($callback)
```

```php
$browser->visit('/')->tap(fn ($browser) => $browser->assertSee('Welcome'));
```

--------------------------------

### Press, clickLink, and attach usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Chains press(), pressAndWaitFor(), clickLink(), and attach() on a browser instance. press() clicks the resolved button; pressAndWaitFor() clicks then waits for re-enable; clickLink() finds a link by text; attach() uploads a local file.

```php
$browser->press('Save')
        ->pressAndWaitFor('Save')
        ->clickLink('Read more')
        ->attach('avatar', __DIR__.'/avatar.png');
```

--------------------------------

### Generic element lookup usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/element-resolver.md

Shows how to use the resolver's find, all, and findOrFail methods. find returns null if the element is missing, all returns an array of matching elements, and findOrFail throws a NoSuchElementException when the element is absent.

```php
$el = $resolver->find('#logo');          // null if missing
$els = $resolver->all('a');               // array of links
try {
    $el = $resolver->findOrFail('#missing');
} catch (\Facebook\WebDriver\Exception\NoSuchElementException $e) {
    // handle absence
}
```

--------------------------------

### Element lookup example: text, attribute, and value methods

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Shows how to read text, read an attribute, and read or write an input value using Dusk's element methods. The value setter writes directly via JavaScript without triggering key events.

```php
$text = $browser->text('.alert');
$href = $browser->attribute('a.logo', 'href');
$old = $browser->value('input[name=q]');   // read
$browser->value('input[name=q]', 'hello'); // write directly (no key events)
```

--------------------------------

### Query string assertions example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-url-assertions.md

Chained assertions for query string parameter presence and absence.

```php
$browser->assertQueryStringHas('page', 2)->assertQueryStringMissing('admin');
```

--------------------------------

### Drag and drop usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Shows chaining drag() and dragRight() on a browser instance. drag() moves an element to a target selector, and dragRight() moves an element by a pixel offset.

```php
$browser->drag('#item', '#dropzone')->dragRight('#slider', 120);
```

--------------------------------

### Example request for dusk.logout endpoint

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/endpoints.md

Shows the HTTP request to log out the current session. The guard parameter is optional and defaults to the configured auth guard.

```http
GET /_dusk/logout
```

--------------------------------

### Authentication assertion usage

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-auth-cookies.md

Example usage of authentication assertions: loginAs, assertAuthenticated, logout, assertGuest, and login with assertAuthenticatedAs.

```php
$browser->loginAs(1)
        ->assertAuthenticated()
        ->logout()
        ->assertGuest();

$browser->login()->assertAuthenticatedAs($user);
```

--------------------------------

### boot() method signature

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/dusk-service-provider.md

The boot method of the DuskServiceProvider. It returns void and is responsible for registering routes and commands.

```php
public function boot()
```

--------------------------------

### OperatingSystem::chromeVersionCommands($operatingSystem)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/operating-system.md

Returns an array of shell commands that report the installed Chrome version for the given operating system ID. Throws an InvalidArgumentException for unknown OS IDs.

```APIDOC
## OperatingSystem::chromeVersionCommands($operatingSystem)

### Description
Returns an array of shell commands that report the installed Chrome version for the given operating system ID.

### Method
Static method

### Signature
`public static function chromeVersionCommands($operatingSystem)`

### Parameters
- **$operatingSystem** (string) - Required - The operating system ID (e.g., 'linux', 'mac', 'mac-intel', 'mac-arm', 'win').

### Returns
- **array<int, string>** - List of detection shell commands.

### Throws
- **\InvalidArgumentException** - If the operating system ID is not in the platform table.

### Example
```php
$commands = OperatingSystem::chromeVersionCommands('linux');
// ['/usr/bin/google-chrome --version', '/usr/bin/chromium-browser --version', ...]
```
```

--------------------------------

### Using OperatingSystem to get OS ID, ChromeDriver slug, and check for Mac

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/operating-system.md

Shows how to use OperatingSystem::id(), chromeDriverSlug(), and onMac() to handle platform-specific logic. The slug for version '120.0' is 'linux64' for Linux, but may differ for other OS IDs.

```php
use Laravel\Dusk\OperatingSystem;

$os = OperatingSystem::id();                       // 'linux' | 'mac-intel' | ...
$slug = OperatingSystem::chromeDriverSlug($os, '120.0'); // 'linux64' ...
if (OperatingSystem::onMac()) {
    // platform-specific key handling
}
```

--------------------------------

### Button, link, and file method signatures

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Lists the public method signatures for press(), pressAndWaitFor(), clickLink(), and attach(). pressAndWaitFor() waits up to 5 seconds for the button to re-enable after clicking. clickLink() uses jQuery and requires ensurejQueryIsAvailable(). attach() installs a LocalFileDetector for real local file uploads.

```php
public function press($button)
public function pressAndWaitFor($button, $seconds = 5)
public function clickLink($link, $element = 'a')
public function attach($field, $path)
```

--------------------------------

### Type, append, send keys, and type slowly

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Demonstrates chaining Dusk's typing methods: type() clears and types, append() adds without clearing, keys() sends raw key strokes (e.g., '{control}', 'a'), and typeSlowly() types with a pause between characters. The example uses a field 'email' and 'bio' with a 150 ms pause.

```php
$browser->type('email', 'taylor@laravel.com')
        ->append('email', '.io')
        ->keys('email', '{control}', 'a')
        ->typeSlowly('bio', 'Hello world', 150);
```

--------------------------------

### OperatingSystem::all()

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/operating-system.md

Returns an array of all supported operating system IDs.

```APIDOC
## OperatingSystem::all()

### Description
Returns an array of all supported operating system IDs.

### Method
Static method

### Signature
`public static function all()`

### Returns
- **array<int, string>** - List of OS IDs: ['linux', 'mac', 'mac-intel', 'mac-arm', 'win'].

### Example
```php
$osList = OperatingSystem::all();
// ['linux', 'mac', 'mac-intel', 'mac-arm', 'win']
```
```

--------------------------------

### Example request for dusk.login endpoint

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/endpoints.md

Shows the HTTP request made by Browser::loginAs(1, 'admin') to the login endpoint. The userId segment can be a numeric ID, UUID string, or email address; the guard is optional and defaults to the configured auth guard.

```http
GET /_dusk/login/1/admin
```

--------------------------------

### click with error handling example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-mouse.md

Example of catching NoSuchElementException when clicking an overlapped element, with a screenshot for debugging.

```php
try {
    $browser->click('#pay-button');
} catch (\Facebook\WebDriver\Exception\NoSuchElementException $e) {
    // no element matched; screenshot for debugging
    $browser->screenshot('pay-missing');
}
```

--------------------------------

### Standard bootstrap with environment gating

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/dusk.md

Combines environment gating with an optional attribute rename in AppServiceProvider::boot(). This ensures DuskServiceProvider only exists in local and testing environments.

```php
// AppServiceProvider::boot()
use Laravel\Dusk\Dusk;

Dusk::register([
    'environments' => ['local', 'testing'],
]);
```

--------------------------------

### login()

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-auth-cookies.md

Logs in as the user resolved by the user resolver closure set in TestCase::setUp().

```APIDOC
## login()

### Description
Logs in as the user resolved by the user resolver closure set in `TestCase::setUp()`. This method uses `call_user_func(Browser::$userResolver)` to determine the user.

### Method
GET

### Endpoint
`/dusk/login` (route: `dusk.login`)

### Parameters
None.

### Request Example
```
GET /dusk/login
```

### Response
#### Success Response (200)
- Returns `$this` for chaining.

#### Response Example
```
Browser instance
```
```

--------------------------------

### withinFrame usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-scoping.md

Example of using `withinFrame` to interact with an iframe. The callback receives a Browser scoped to the frame, allowing assertions like `assertSee` within that frame.

```php
$browser->withinFrame('#payments-iframe', function ($browser) {
    $browser->assertSee('Card number');
});
```

--------------------------------

### Register Dusk in AppServiceProvider::boot()

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/dusk.md

Shows the typical usage of Dusk::register() inside AppServiceProvider::boot() to enable Dusk only for local and testing environments.

```php
// Typically in AppServiceProvider::boot():
Dusk::register(['environments' => ['local', 'testing']]);
```

--------------------------------

### Constructor

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser.md

Creates a new Browser instance with a WebDriver session and optional element resolver.

```APIDOC
## Constructor

### Description
Creates a new Browser instance with a WebDriver session and optional element resolver.

### Method
`__construct`

### Signature
```php
public function __construct($driver, $resolver = null)
```

### Parameters
- `$driver` (\Facebook\WebDriver\Remote\RemoteWebDriver) - Required - Live WebDriver session
- `$resolver` (\Laravel\Dusk\ElementResolver) - Optional - Element resolver; defaults to `new ElementResolver($driver)` scoped to `body`

### Returns
void
```

--------------------------------

### Using withKeyboard for key sequences and modifier combos

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/keyboard.md

Shows how to use Browser::withKeyboard() to press and release keys, type sequences, and perform a modifier-click combo (e.g., control-click) with platform-specific modifier keys.

```php
$browser->withKeyboard(function ($keyboard) {
    $keyboard->press('{shift}')->type('HELLO')->release('{shift}');
    $keyboard->type(['{control}', 'a']);   // forward to RemoteKeyboard
});

// Modifier-combo pattern from Browser::controlClick():
$browser->withKeyboard(function ($keyboard) use ($selector) {
    $key = \Laravel\Dusk\OperatingSystem::onMac()
        ? \Facebook\WebDriver\WebDriverKeys::META
        : \Facebook\WebDriver\WebDriverKeys::CONTROL;

    $keyboard->press($key);
    $browser->click($selector);
    $keyboard->release($key);
});
```

--------------------------------

### assertSourceHas and assertSourceMissing usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-assertions.md

Example showing how to assert that the page source contains a specific HTML snippet and does not contain another. These methods set a flag that triggers source logging on failure.

```php
$browser->assertSourceHas('<div id="app">')->assertSourceMissing('<script src="evil.js">');
```

--------------------------------

### Keyboard::__construct(Browser $browser)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/keyboard.md

Creates a new Keyboard instance bound to the given Browser. Typically obtained through Browser::withKeyboard().

```APIDOC
## Keyboard::__construct(Browser $browser)

### Description
Creates a new Keyboard instance that wraps the WebDriver remote keyboard for the given browser.

### Method
Constructor

### Signature
`public function __construct(Browser $browser)`

### Parameters
- **$browser** (\Laravel\Dusk\Browser) - Required - The owning browser instance.

### Usage
```php
$browser->withKeyboard(function ($keyboard) {
    // $keyboard is a Keyboard instance
});
```
```

--------------------------------

### Command signature and options

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-driver-command.md

Shows the command signature and available options: `version` argument, `--all`, `--detect`, `--proxy`, and `--ssl-no-verify`.

```bash
dusk:chrome-driver {version?}
    {--all : Install a ChromeDriver binary for every OS}
    {--detect : Detect the installed Chrome / Chromium version}
    {--proxy= : The proxy to download the binary through (example: "tcp://127.0.0.1:9000")}
    {--ssl-no-verify : Bypass SSL certificate verification when installing through a proxy}
```

--------------------------------

### scrollTo() usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Scrolls to the element with id 'footer'.

```php
$browser->scrollTo('#footer');
```

--------------------------------

### withKeyboard(callable $callback)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Invokes a callback with a new Keyboard instance for performing keyboard actions.

```APIDOC
## withKeyboard(callable $callback)

### Description
Invokes a callback with a new Keyboard instance for performing keyboard actions.

### Method
`withKeyboard`

### Signature
```php
public function withKeyboard(callable $callback)
```

### Parameters
- **$callback** (callable) - Required - A callable that receives a `\Laravel\Dusk\Keyboard` instance.

### Returns
`$this`

### Example
```php
$browser->withKeyboard(function ($keyboard) {
    $keyboard->press('{shift}')->type('Hello')->release('{shift}');
});
```
```

--------------------------------

### screenshot($name)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Writes `{storeScreenshotsAt}/{name}.png`, creating directories as needed. Returns `$this`.

```APIDOC
## screenshot($name)

### Description
Writes `{storeScreenshotsAt}/{name}.png`, creating directories as needed.

### Method
`screenshot($name)`

### Parameters
- `$name` (string) - Required - File base name (no extension needed)

### Returns
`$this`

### Example
```php
$browser->screenshot('homepage');
```
```

--------------------------------

### Override selector attribute to data-dusk

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/dusk.md

Shows how to change the selector attribute to 'data-dusk' and the resulting effect on @example selectors.

```php
Dusk::selectorHtmlAttribute('data-dusk');
// now @example resolves to [data-dusk="example"]
```

--------------------------------

### RemoteWebDriver::create() call

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/test-case.md

Creates a RemoteWebDriver using the DUSK_DRIVER_URL environment variable or default localhost:9515 with Chrome capabilities.

```php
RemoteWebDriver::create(
    $_ENV['DUSK_DRIVER_URL'] ?? env('DUSK_DRIVER_URL') ?? 'http://localhost:9515',
    DesiredCapabilities::chrome()
)
```

--------------------------------

### disableFitOnFailure() usage example

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Disables content fitting before visiting a responsive page, affecting failure screenshot capture.

```php
$browser->disableFitOnFailure()->visit('/responsive-page');
```

--------------------------------

### ChromeProcess::__construct

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/chrome-process.md

Constructor for ChromeProcess. Accepts an optional custom Chromedriver binary path; if null, resolves a per-OS binary in dusk/bin/.

```APIDOC
## ChromeProcess::__construct

### Description
Creates a new ChromeProcess instance. If a custom driver path is provided, it will be used; otherwise, a per-OS binary in dusk/bin/ is resolved.

### Method
Constructor

### Signature
```php
public function __construct($driver = null)
```

### Parameters
- **$driver** (string|null) - Optional - Path to a custom Chromedriver binary. Defaults to null.

### Example
```php
$process = new ChromeProcess('/path/to/chromedriver');
```
```

--------------------------------

### waitForLocation

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-waits.md

Waits until the browser's location path matches the given path, or full URL if the path starts with http:// or https://.

```APIDOC
## waitForLocation

### Description
Waits until the browser's `window.location.pathname` equals the given `$path`, or the full `scheme://host/path` when `$path` starts with `http://` or `https://`.

### Method
`waitForLocation($path, $seconds = null)`

### Parameters
- **$path** (string) - Required - The path or full URL to wait for.
- **$seconds** (int|null) - Optional - Maximum number of seconds to wait. Defaults to the default wait time.

### Example
```php
$browser->click('#login')->waitForLocation('/dashboard');
```
```

--------------------------------

### cookie($name, $value = null, $expiry = null, array $options = [])

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-auth-cookies.md

Gets the decrypted value of a cookie, or sets a cookie with encryption when a non-null value is provided.

```APIDOC
## cookie($name, $value = null, $expiry = null, array $options = [])

### Description
Gets the decrypted value of a cookie, or sets a cookie with encryption when a non-null value is provided.

### Method
cookie

### Signature
`public function cookie($name, $value = null, $expiry = null, array $options = [])`

### Parameters
- `$name` (string) - Required - Cookie name
- `$value` (string/null) - Optional - Value; when null the method acts as a getter
- `$expiry` (int/\DateTimeInterface/null) - Optional - Unix timestamp or datetime (converted via `getTimestamp()`)
- `$options` (array) - Optional - Extra cookie options (path, domain, secure, httpOnly, sameSite) merged into the cookie payload

### Behavior
- Getter: returns decrypted value or `null`.
- Setter (non-null `$value`): calls `addCookie()` with encryption.
```

--------------------------------

### plainCookie($name, $value = null, $expiry = null, array $options = [])

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-auth-cookies.md

Gets the raw URL-decoded value of a cookie, or sets a cookie without encryption when a non-null value is provided.

```APIDOC
## plainCookie($name, $value = null, $expiry = null, array $options = [])

### Description
Gets the raw URL-decoded value of a cookie, or sets a cookie without encryption when a non-null value is provided.

### Method
plainCookie

### Signature
`public function plainCookie($name, $value = null, $expiry = null, array $options = [])`

### Parameters
- `$name` (string) - Required - Cookie name
- `$value` (string/null) - Optional - Value; when null the method acts as a getter
- `$expiry` (int/\DateTimeInterface/null) - Optional - Unix timestamp or datetime (converted via `getTimestamp()`)
- `$options` (array) - Optional - Extra cookie options (path, domain, secure, httpOnly, sameSite) merged into the cookie payload

### Behavior
- Getter: returns raw `rawurldecode()`d value or `null`.
- Setter: calls `addCookie(..., encrypt: false)`.
```

--------------------------------

### Register Dusk HTTP routes in DuskServiceProvider::boot()

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/endpoints.md

Routes are registered only when the app environment is not 'production'. The route group uses config values for prefix (default '_dusk'), domain (default null), and middleware (default 'web'). All routes are GET-only and require no authentication headers.

```php
if (! $this->app->environment('production')) {
    Route::group(array_filter([
        'prefix' => config('dusk.path', '_dusk'),
        'domain' => config('dusk.domain', null),
        'middleware' => config('dusk.middleware', 'web'),
    ]), function () {
        Route::get('/login/{userId}/{guard?}', ['uses' => 'Laravel\Dusk\Http\Controllers\UserController@login',  'as' => 'dusk.login']);
        Route::get('/logout/{guard?}',          ['uses' => 'Laravel\Dusk\Http\Controllers\UserController@logout', 'as' => 'dusk.logout']);
        Route::get('/user/{guard?}',            ['uses' => 'Laravel\Dusk\Http\Controllers\UserController@user',   'as' => 'dusk.user']);
    });
}
```

--------------------------------

### loginAs($userId, $guard = null)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-auth-cookies.md

Logs in as the given user by visiting the dusk.login route. The user can be specified by ID, email, or an object with a getKey method.

```APIDOC
## loginAs($userId, $guard = null)

### Description
Logs in as the given user by visiting the `dusk.login` route. The user can be specified by ID, email, or an object with a `getKey` method.

### Method
GET

### Endpoint
`/dusk/login` (route: `dusk.login`)

### Parameters
#### Path Parameters
- `userId` (string|int) - Required - The user ID or email (if contains `@`) or object with `getKey()`.
- `guard` (string|null) - Optional - The auth guard to use; defaults to `null` (default guard).

### Request Example
```
GET /dusk/login?userId=1&guard=null
```

### Response
#### Success Response (200)
- Redirects to the previous page after login.

#### Response Example
```
302 Redirect
```
```

--------------------------------

### GET /{prefix}/logout/{guard?}

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/endpoints.md

Logs the current session out. The guard parameter is optional and defaults to the application's default auth guard. This endpoint clears the password confirmation hash for the guard.

```APIDOC
## GET /{prefix}/logout/{guard?}

### Description
Logs the current session out. The guard parameter is optional and defaults to the application's default auth guard. This endpoint clears the password confirmation hash for the guard.

### Method
GET

### Endpoint
/{prefix}/logout/{guard?}

### Parameters
#### Path Parameters
- **guard** (string) - Optional - Guard to log out. Defaults to config('auth.defaults.guard').

### Request Example
GET /_dusk/logout

### Response
#### Success Response (200)
Empty page.

#### Response Example
(No response body specified)
```

--------------------------------

### onComponent($component, $parentResolver)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-scoping.md

Activates a component on the current browser instance, merging element shortcuts and running the component's assert method. Returns void.

```APIDOC
## onComponent($component, $parentResolver)

### Description
Activates a component on the current browser instance, merging element shortcuts and running the component's assert method. Returns void.

### Method
PHP method

### Signature
public function onComponent($component, $parentResolver)

### Parameters
- **$component** (Component) - Required - Component to activate
- **$parentResolver** (ElementResolver) - Required - Parent resolver whose `elements` are merged

### Returns
void

### Behavior
Sets `$this->component`, merges `$component->elements() + $parentResolver->elements` into the resolver, runs `$component->assert($this)`, then sets the resolver prefix to `format($component->selector())`.
```

--------------------------------

### GET /{prefix}/user/{guard?}

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/endpoints.md

Reports the currently authenticated user. Used by assertAuthenticated, assertGuest, and assertAuthenticatedAs. Returns a JSON array with user ID and class name, or an empty array if no user is authenticated.

```APIDOC
## GET /{prefix}/user/{guard?}

### Description
Reports the currently authenticated user. Used by `assertAuthenticated` / `assertGuest` / `assertAuthenticatedAs`.

### Method
GET

### Endpoint
`/{prefix}/user/{guard?}`

### Parameters
#### Path Parameters
- **guard** (string) - Optional - Guard to inspect; defaults to `config('auth.defaults.guard')`.

### Response
#### Success Response (200)
- **id** (mixed) - Present when authenticated - `$user->getAuthIdentifier()`
- **className** (string) - Present when authenticated - `get_class($user)`

When no user is authenticated, the response is an empty JSON array (`[]`).

#### Response Example
```
GET /_dusk/user
→ 200 application/json: {"id":1,"className":"App\\Models\\User"}

GET /_dusk/user (guest)
→ 200 application/json: []
```
```

--------------------------------

### responsiveScreenshots($name)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Captures responsive screenshots for each configured device size. Iterates over the responsive screen sizes and saves a screenshot for each, appending the device name to the file base name.

```APIDOC
## responsiveScreenshots($name)

### Description
Captures a screenshot for each responsive device size defined in `Browser::$responsiveScreenSizes` (xs, sm, md, lg, xl, 2xl). Each screenshot is saved with the base name followed by a dash and the device name.

### Method
PHP method

### Signature
```php
public function responsiveScreenshots($name)
```

### Parameters
- **$name** (string) - Required - File base name; a dash is appended unless the name already ends with a slash.

### Returns
`$this` (fluent interface)

### Example
```php
$browser->responsiveScreenshots('welcome');
// produces welcome-xs.png ... welcome-2xl.png
```
```

--------------------------------

### handle() method signature

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/console-commands.md

The public method signature for the 'dusk' command's handle method. It is the entry point for running Dusk tests.

```php
public function handle()
```

--------------------------------

### value($selector, $value = null)

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Gets or sets the value of an input element. When called with only a selector, it returns the current value. When called with a value, it sets the input's value directly without key events.

```APIDOC
## value($selector, $value = null)

### Description
Gets or sets the value of an input element. When called with only a selector, it returns the current value. When called with a value, it sets the input's value directly without key events.

### Method
`value`

### Signature
`public function value($selector, $value = null)`

### Parameters
- `$selector` (string) - Required - CSS selector (resolver-formatted)
- `$value` (string/null) - Optional - Default: `null` - When given, sets the input's `value` via `document.querySelector(...).value = ...`

### Returns
- Getter: `string|true|null`
- Setter: `$this`

### Example
```php
$old = $browser->value('input[name=q]');   // read
$browser->value('input[name=q]', 'hello'); // write directly (no key events)
```
```

--------------------------------

### elements() method

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/component.md

Shows the elements() method signature that returns an array of component-local element shortcuts.

```php
public function elements()
```

--------------------------------

### Keyboard constructor signature

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/keyboard.md

Constructor for the Keyboard class, accepting the owning Browser instance.

```php
public function __construct(Browser $browser)
```

--------------------------------

### move() method signature

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-window.md

Signature for the move() method. Takes x and y screen coordinates, returns $this, positions the window with a new WebDriverPoint.

```php
public function move($x, $y)
```

--------------------------------

### withKeyboard method signature

Source: https://github.com/laravel/dusk/blob/8.x/_autodocs/api-reference/browser-elements.md

Signature for withKeyboard() which accepts a callback receiving a Keyboard instance. Returns $this.

```php
public function withKeyboard(callable $callback)
```
Tokens:
Raw