Avoid retrying side-effecting browser actions

package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "playwright": "^1.59.1"
+    "playwright": "^1.60.0"
   }
 }

src/Api/AwaitableWebpage.php

@@ -17,6 +17,24 @@
  */
 final readonly class AwaitableWebpage
 {
+    private const array NON_RETRYABLE_ACTION_METHODS = [
+        'click',
+        'press',
+        'pressAndWaitFor',
+        'submit',
+        'type',
+        'typeSlowly',
+        'fill',
+        'rightClick',
+        'select',
+        'append',
+        'clear',
+        'radio',
+        'check',
+        'uncheck',
+        'attach',
+    ];
+
     /**
      * Creates a new awaitable webpage instance.
      *
@@ -34,22 +52,23 @@ public function __construct(
     }
 
     /**
-     * Awaits for the given method to assert true or fail.
-     *
      * @param  array<int, mixed>  $arguments
      */
     public function __call(string $name, array $arguments): mixed
     {
         $webpage = new Webpage($this->page, $this->initialUrl);
 
         try {
-            if (
-                in_array($name, $this->nonAwaitableMethods, true)
-                || Playwright::timeout() <= 1000
-            ) {
-                // @phpstan-ignore-next-line
-                $result = $webpage->{$name}(...$arguments);
+            if ($this->shouldRunOnce($name)) {
+                // Actions should be attempted once.
+                // Playwright itself will wait for actionability up to the configured timeout.
+                $result = Playwright::usingTimeout(
+                    Playwright::timeout(),
+                    // @phpstan-ignore-next-line
+                    fn () => $webpage->{$name}(...$arguments),
+                );
             } else {
+                // Assertions/read expectations may be retried until the browser timeout expires.
                 $result = Execution::instance()->waitForExpectation(
                     // @phpstan-ignore-next-line
                     fn () => $webpage->{$name}(...$arguments),
@@ -60,7 +79,7 @@ public function __call(string $name, array $arguments): mixed
 
             try {
                 $browserException = BrowserExpectationFailedException::from($this->page, $e);
-            } catch (Throwable) { // @phpstan-ignore-line
+            } catch (Throwable) {
                 throw $e;
             }
 
@@ -69,16 +88,18 @@ public function __call(string $name, array $arguments): mixed
 
         ServerManager::instance()->http()->throwLastThrowableIfNeeded();
 
-        return $result === $webpage
-            ? $this
-            : $result;
+        return $result === $webpage ? $this : $result;
     }
 
-    /**
-     * Return the page instance.
-     */
     public function page(): Page
     {
         return $this->page;
     }
+
+    private function shouldRunOnce(string $name): bool
+    {
+        return in_array($name, $this->nonAwaitableMethods, true)
+            || in_array($name, self::NON_RETRYABLE_ACTION_METHODS, true)
+            || Playwright::timeout() <= 1000;
+    }
 }

src/Api/Concerns/InteractsWithElements.php

@@ -16,7 +16,7 @@ trait InteractsWithElements
      */
     public function click(string $text): self
     {
-        $this->guessLocator($text)->click();
+        $this->guessClickableLocator($text)->click();
 
         return $this;
     }
@@ -62,7 +62,7 @@ public function keys(string $selector, array|string $keys): self
      */
     public function type(string $field, string $value): self
     {
-        $this->guessLocator($field)->fill($value);
+        $this->guessFieldLocator($field)->fill($value);
 
         return $this;
     }
@@ -74,7 +74,7 @@ public function typeSlowly(string $field, string $value, int $delay = 100): self
     {
         $options = ['delay' => $delay];
 
-        $this->guessLocator($field)->type($value, $options);
+        $this->guessFieldLocator($field)->type($value, $options);
 
         return $this;
     }
@@ -102,7 +102,7 @@ public function hover(string $selector): self
      */
     public function rightClick(string $text): Webpage
     {
-        $this->guessLocator($text)->click([
+        $this->guessClickableLocator($text)->click([
             'button' => 'right',
         ]);
 
@@ -116,7 +116,7 @@ public function rightClick(string $text): Webpage
      */
     public function select(string $field, array|string|int $option): self
     {
-        $this->guessLocator($field)->selectOption($option);
+        $this->guessSelectableLocator($field)->selectOption($option);
 
         return $this;
     }
@@ -126,7 +126,7 @@ public function select(string $field, array|string|int $option): self
      */
     public function append(string $field, string $value): self
     {
-        $locator = $this->guessLocator($field);
+        $locator = $this->guessFieldLocator($field);
 
         $currentValue = $locator->inputValue();
 
@@ -140,7 +140,7 @@ public function append(string $field, string $value): self
      */
     public function clear(string $field): self
     {
-        $this->guessLocator($field)->clear();
+        $this->guessFieldLocator($field)->clear();
 
         return $this;
     }
@@ -150,7 +150,7 @@ public function clear(string $field): self
      */
     public function radio(string $field, string $value): self
     {
-        $this->guessLocator($field, $value)->click();
+        $this->guessCheckableLocator($field, $value)->click();
 
         return $this;
     }
@@ -160,7 +160,7 @@ public function radio(string $field, string $value): self
      */
     public function check(string $field, ?string $value = null): self
     {
-        $this->guessLocator($field, $value)->check();
+        $this->guessCheckableLocator($field, $value)->check();
 
         return $this;
     }
@@ -170,7 +170,7 @@ public function check(string $field, ?string $value = null): self
      */
     public function uncheck(string $field, ?string $value = null): self
     {
-        $this->guessLocator($field, $value)->uncheck();
+        $this->guessCheckableLocator($field, $value)->uncheck();
 
         return $this;
     }
@@ -180,7 +180,7 @@ public function uncheck(string $field, ?string $value = null): self
      */
     public function attach(string $field, string $path): self
     {
-        $this->guessLocator($field)->setInputFiles($path);
+        $this->guessFieldLocator($field)->setInputFiles($path);
 
         return $this;
     }

src/Api/Webpage.php

@@ -4,7 +4,6 @@
 
 namespace Pest\Browser\Api;
 
-use Pest\Browser\Execution;
 use Pest\Browser\Playwright\Locator;
 use Pest\Browser\Playwright\Page;
 use Pest\Browser\Support\GuessLocator;
@@ -74,7 +73,7 @@ public function url(): string
      */
     public function submit(): self
     {
-        $this->guessLocator('[type="submit"]')->click();
+        $this->guessClickableLocator('[type="submit"]')->click();
 
         return $this;
     }
@@ -102,4 +101,24 @@ private function guessLocator(string $selector, ?string $value = null): Locator
     {
         return (new GuessLocator($this->page))->for($selector, $value);
     }
+
+    private function guessClickableLocator(string $selector): Locator
+    {
+        return (new GuessLocator($this->page))->forClickable($selector);
+    }
+
+    private function guessFieldLocator(string $selector): Locator
+    {
+        return (new GuessLocator($this->page))->forField($selector);
+    }
+
+    private function guessCheckableLocator(string $selector, ?string $value = null): Locator
+    {
+        return (new GuessLocator($this->page))->forCheckable($selector, $value);
+    }
+
+    private function guessSelectableLocator(string $selector): Locator
+    {
+        return (new GuessLocator($this->page))->forSelectable($selector);
+    }
 }