From ab458a7d2b5ce67a046db3c5b8a08e94453dc97a Mon Sep 17 00:00:00 2001
From: DanielGSoftware <danielgsoftware@gmail.com>
Date: Thu, 2 Jul 2026 10:49:07 +0200
Subject: [PATCH] feat: allow passing options to click() and press()

Forwards an optional array of Playwright locator options through click()
and press() to the underlying locator. This enables options such as
noWaitAfter for actions that trigger a navigation, which otherwise hang
(see pestphp/pest#1511).
---
 src/Api/Concerns/InteractsWithElements.php | 12 ++++++++----
 tests/Browser/Webpage/ClickTest.php        | 16 ++++++++++++++++
 tests/Browser/Webpage/PressTest.php        | 13 +++++++++++++
 3 files changed, 37 insertions(+), 4 deletions(-)

diff --git a/src/Api/Concerns/InteractsWithElements.php b/src/Api/Concerns/InteractsWithElements.php
index 24566e7e..1c8a1c32 100644
--- a/src/Api/Concerns/InteractsWithElements.php
+++ b/src/Api/Concerns/InteractsWithElements.php
@@ -13,10 +13,12 @@ trait InteractsWithElements
 {
     /**
      * Click the link with the given text.
+     *
+     * @param  array<string, mixed>|null  $options
      */
-    public function click(string $text): self
+    public function click(string $text, ?array $options = null): self
     {
-        $this->guessLocator($text)->click();
+        $this->guessLocator($text)->click($options);
 
         return $this;
     }
@@ -187,10 +189,12 @@ public function attach(string $field, string $path): self
 
     /**
      * Press the button with the given text or name.
+     *
+     * @param  array<string, mixed>|null  $options
      */
-    public function press(string $button): self
+    public function press(string $button, ?array $options = null): self
     {
-        return $this->click($button);
+        return $this->click($button, $options);
     }
 
     /**
diff --git a/tests/Browser/Webpage/ClickTest.php b/tests/Browser/Webpage/ClickTest.php
index 0396359e..cfb689e8 100644
--- a/tests/Browser/Webpage/ClickTest.php
+++ b/tests/Browser/Webpage/ClickTest.php
@@ -73,3 +73,19 @@
     '[name$="test"]',
     'button[name="test"]',
 ]);
+
+it('forwards options to the underlying click', function (): void {
+    Route::get('/', fn (): string => '
+        <button oncontextmenu="event.preventDefault(); document.getElementById(\'result\').textContent = \'Right Clicked\'">Menu</button>
+        <div id="result"></div>
+    ');
+
+    $page = visit('/');
+
+    // A left click would never fire the contextmenu handler, so this proves the
+    // `button` option reaches the underlying Playwright locator. The motivating
+    // use case is passing `noWaitAfter` for clicks that trigger a navigation.
+    $page->click('Menu', ['button' => 'right']);
+
+    expect($page->text('#result'))->toBe('Right Clicked');
+});
diff --git a/tests/Browser/Webpage/PressTest.php b/tests/Browser/Webpage/PressTest.php
index 2fc8b448..7a046dc7 100644
--- a/tests/Browser/Webpage/PressTest.php
+++ b/tests/Browser/Webpage/PressTest.php
@@ -91,3 +91,16 @@
 
     expect($page->text('#result'))->toBe('Input Button Pressed');
 });
+
+it('forwards options to the underlying press', function (): void {
+    Route::get('/', fn (): string => '
+        <button oncontextmenu="event.preventDefault(); document.getElementById(\'result\').textContent = \'Right Pressed\'">Submit</button>
+        <div id="result"></div>
+    ');
+
+    $page = visit('/');
+
+    $page->press('Submit', ['button' => 'right']);
+
+    expect($page->text('#result'))->toBe('Right Pressed');
+});