feat: add slow-motion support to ease debugging

src/Configuration.php

@@ -85,6 +85,16 @@ public function headed(): self
         return $this;
     }
 
+    /**
+     * Slows down each browser action by the given number of milliseconds.
+     */
+    public function slowMo(int $milliseconds = Playwright::DEFAULT_SLOW_MO): self
+    {
+        Playwright::setSlowMo($milliseconds);
+
+        return $this;
+    }
+
     /**
      * Sets the browsers userAgent.
      */

src/Playwright/Client.php

@@ -53,6 +53,7 @@ public function connectTo(string $url): void
 
             $launchOptions = json_encode([
                 'headless' => Playwright::isHeadless(),
+                'slowMo' => Playwright::slowMo(),
                 'ignoreHTTPSErrors' => true,
                 'bypassCSP' => true,
             ]);

src/Playwright/Playwright.php

@@ -12,6 +12,12 @@
  */
 final class Playwright
 {
+    /**
+     * The default slow-motion delay, in milliseconds, used when `--slow-mo` is
+     * passed without a value.
+     */
+    public const int DEFAULT_SLOW_MO = 500;
+
     /**
      * Browser types
      *
@@ -49,6 +55,11 @@ final class Playwright
      */
     private static int $timeout = 5_000;
 
+    /**
+     * The delay, in milliseconds, applied before each browser action.
+     */
+    private static int $slowMo = 0;
+
     /**
      * The default userAgent.
      */
@@ -131,6 +142,22 @@ public static function timeout(): int
         return self::$timeout;
     }
 
+    /**
+     * Set the delay, in milliseconds, applied before each browser action.
+     */
+    public static function setSlowMo(int $milliseconds): void
+    {
+        self::$slowMo = $milliseconds;
+    }
+
+    /**
+     * Get the delay, in milliseconds, applied before each browser action.
+     */
+    public static function slowMo(): int
+    {
+        return self::$slowMo;
+    }
+
     /**
      * Set the default userAgent.
      */

src/Plugin.php

@@ -118,6 +118,24 @@ public function handleArguments(array $arguments): array
             $arguments = array_values($arguments);
         }
 
+        if ($this->hasArgument('--slow-mo', $arguments)) {
+            $index = array_search('--slow-mo', $arguments, true);
+
+            // `--slow-mo` may be passed bare (uses a sensible default) or with an
+            // explicit millisecond value: `--slow-mo 250`.
+            if ($index !== false && isset($arguments[$index + 1]) && is_numeric($arguments[$index + 1])) {
+                Playwright::setSlowMo((int) $arguments[$index + 1]);
+
+                unset($arguments[$index], $arguments[$index + 1]);
+            } else {
+                Playwright::setSlowMo(Playwright::DEFAULT_SLOW_MO);
+
+                unset($arguments[$index]);
+            }
+
+            $arguments = array_values($arguments);
+        }
+
         $this->validateNonSupportedParallelFeatures();
 
         return $arguments;

tests/Unit/Configuration/SlowMoConfigurationTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+use Pest\Browser\Configuration;
+use Pest\Browser\Playwright\Playwright;
+
+beforeEach(function (): void {
+    // Reset Playwright state before each test
+    Playwright::setSlowMo(0);
+});
+
+it('defaults slow motion to zero', function (): void {
+    expect(Playwright::slowMo())->toBe(0);
+});
+
+it('can set slow motion via configuration', function (): void {
+    $config = new Configuration();
+
+    $result = $config->slowMo(250);
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::slowMo())->toBe(250);
+});
+
+it('uses a sensible default when no value is given', function (): void {
+    $config = new Configuration();
+
+    $config->slowMo();
+
+    expect(Playwright::slowMo())->toBe(Playwright::DEFAULT_SLOW_MO);
+});
+
+it('follows fluent interface pattern', function (): void {
+    $config = new Configuration();
+
+    $result = $config
+        ->slowMo(500)
+        ->timeout(10000);
+
+    expect($result)->toBeInstanceOf(Configuration::class);
+    expect(Playwright::slowMo())->toBe(500);
+});
+
+it('stores slow motion in Playwright global state', function (): void {
+    expect(Playwright::slowMo())->toBe(0);
+
+    Playwright::setSlowMo(1000);
+
+    expect(Playwright::slowMo())->toBe(1000);
+});