repository·8.x·Indexed 24 days ago
https://github.com/laravel/duskA browser automation and testing tool for Laravel that provides an expressive API for end-to-end testing. It allows developers to simulate user interactions in a real browser environment using a standalone Chromedriver or other Selenium drivers. Key features include browser window management, screenshot and log capture, scoped interactions via within(), and specialized DOM element resolution for various input types.
Laravel Dusk is a browser automation and testing API designed to be expressive and easy to use. It allows you to write tests that interact with your application through a real browser.
By default, Dusk simplifies setup by using a standalone Chromedriver, meaning you do not need to manually install the JDK or Selenium on your machine. However, the system is flexible enough to allow you to use any other Selenium driver if required.
--pest option has been removed from the dusk Artisan command; Dusk will now automatically detect and use Pest if it is installed in your project.Keyboard class uses the __call magic method to proxy calls to the underlying Facebook\WebDriver\Remote\RemoteKeyboard instance. If a method is not explicitly defined in the Keyboard class, Dusk will attempt to find and execute it on the driver's keyboard object. This allows you to use any native WebDriver keyboard functionality that might not be explicitly wrapped by Dusk.Dusk allows you to scope browser actions to specific elements or components using closures. This changes the context of the ElementResolver so that subsequent commands are relative to that scope.
within($selector, Closure $callback): Executes a callback where all interactions are scoped inside the provided $selector.elsewhere($selector, Closure $callback): Executes a callback where interactions are scoped to the provided $selector, but the selector is treated as being relative to the body (effectively escaping the current scope).withinFrame($selector, Closure $callback): Specifically used to switch into an iframe, execute the callback, and then automatically switch back to the default content.Run the dusk:install command to scaffold the necessary testing directories and files for Laravel Dusk. This command creates the tests/Browser directory structure (including Pages, Components, screenshots, console, and source) and copies stub files for HomePage, DuskTestCase, Page, and example tests. It also attempts to download the required ChromeDriver binaries via the dusk:chrome-driver command.
If you are using Pest, the installer will automatically configure tests/Pest.php to include Tests\DuskTestCase::class for the Browser directory.
The Browser class uses several static properties to configure global behavior. These are typically set in your DuskTestCase:
static::$baseUrl: The base URL for all relative URLs.static::$storeScreenshotsAt: Directory for screenshots.static::$storeConsoleLogAt: Directory for console logs.static::$storeSourceAt: Directory for source code snapshots.static::$waitSeconds: Default wait time in seconds (default: 5).static::$ignoreConsoleMessages: Array of strings to ignore when capturing logs (e.g., ['favicon.ico']).static::$responsiveScreenSizes: Array defining the width/height for responsiveScreenshots().The ElementResolver class provides specialized methods to locate specific types of web elements using intuitive identifiers (like field names) rather than complex CSS selectors. It attempts to find elements by ID first before falling back to name-based or type-specific selectors.
resolveForTyping($field) to find an element suitable for text input (searches for input[name='...'], textarea[name='...'], or the selector itself).resolveForSelection($field) to find a <select> element.resolveSelectOptions($field, array $values) to retrieve an array of RemoteWebElement objects representing <option> tags within a select field that match the provided values.resolveForRadioSelection($field, $value) to find a specific radio button by its name and value.resolveForChecking($field, $value) to find a checkbox by name and/or value.resolveForAttachment($field) to find an <input type='file'> element.resolveForField($field) as a broad fallback for inputs, textareas, selects, or buttons.resolveForButtonPress($button) to find a button using several strategies: selector, name, value, or text (supports both exact and partial text matches).The format($selector) method prepares a selector for use with the WebDriver. It performs three main actions:
$elements array (via pageElements()) with their corresponding CSS selectors.@ (e.g., @my-attribute), it converts it into a CSS attribute selector using the internal Dusk::$selectorHtmlAttribute (e.g., [data-dusk="my-attribute"]).$prefix (defaults to body) to the selector to scope the search.The ElementResolver provides two primary ways to locate elements with strict error handling:
findOrFail($selector): Attempts to find an element by ID (if the selector starts with #) or via a CSS selector. Throws an exception if the element is not found.firstOrFail(array $selectors): Iterates through an array of selectors and returns the first one that successfully resolves an element. Throws an exception if none of the selectors match.When a test fails or you need to inspect the browser state mid-test, use these debugging tools:
tinker(): Pauses test execution and opens a Laravel Tinker (PsySH) REPL, providing access to the $browser, $driver, $resolver, and $page objects.dd(): Dumps the current page source and immediately quits the browser and exits the script.dump(): Dumps the current page source to the console without stopping execution.