Add waitForEvent() method

[michaelhue]

This pull requests adds a waitForEvent() method to the WaitsForElements trait, making it available to the Browser class.

It also adds a corresponding test case to WaitsForElementsTest.

Explanation

waitForEvent(
    string $type,
    ?string $target = null,
    ?int $seconds = null
): self

The waitForEvent() method pauses the test execution until a given event type occurs on a target element or object.

This is especially useful when working with front-end libraries like InertiaJS or Hotwire/Turbo, since those libraries will trigger events that can be very helpful for automated testing. For example, clicking a link and waiting for the inertia:navigate event before continuing with the test.

Usage examples

Waiting for events on DOM elements:

// Targeting the body element
$browser->waitForEvent('load');

// Targeting CSS selectors
$browser->waitForEvent('load', 'img');

// Targeting scoped selectors
$browser->with('img', function ($img) {
	$img->waitForEvent('load');
});

// Targeting dusk selectors
$browser->waitForEvent('load', '@dusk-selector');

Waiting for events on document or window:

$browser->waitForEvent('scroll', 'document');
$browser->waitForEvent('resize', 'window');

Waiting for InertiaJS events:

$browser->visit('/login')
	->waitForEvent('inertia:navigate', 'document');
	
$browser->press('Submit')
	->waitForEvent('inertia:finish', 'document');

Waiting for events with a custom timeout in seconds:

$browser->waitForEvent('load', 'img.huge-image', 10);

Discussion

I’m very open to suggestions on how to improve this. A few thoughts:

I’m not huge fan of the $target argument being either a selector or 'document' / 'window', since it’s not very clearly communicated. Adding a description for $target in the docblock could help, but that would be inconsistent with the rest of the Dusk codebase.

I also thought about adding different methods for differentiation:

waitForEvent(string $type, ?string $selector = null);
// or…
waitForElementEvent(string $type, ?string $selector = null);

// …and…
waitForDocumentEvent(string $type);
waitForWindowEvent(string $type);

But in the end I opted for a single method, since I felt it still had the best developer ergonomics.

—

I see potential for more convenience methods using events, for example:

• visitAndWaitForEvent()
• visitRouteAndWaitForEvent()
• clickLinkAndWaitForEvent()
• pressAndWaitForEvent()

Should these methods be desirable in the future, maybe a dedicated WaitsForEvents or InteractsWithEvents trait would be good.

—

Finally I’m unsure about using eval() in the executeAsyncScript() call. But I like that it makes the JavaScript code very concise since it works with object names (document/window) and element references at the same time. Also in a testing environment, I feel eval() is not that dramatic. Maybe it could lead to problems with content security policies, I’m not sure how Dusk/WebDriver handles those.

[taylorotwell]

Can you submit a docs PR to laravel/docs?

[michaelhue]

Sure!

Thanks for the merge Taylor!