Add playwright tracing support

.gitignore

@@ -13,6 +13,7 @@ coverage.xml
 # Playwright
 node_modules/
 /tests/Browser/Screenshots
+/tests/Browser/Tracing
 
 # MacOS
 .DS_Store

src/Api/Concerns/HasTracing.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Browser\Api\Concerns;
+
+use Pest\Browser\Api\Webpage;
+use Pest\Browser\Playwright\Tracing;
+
+/**
+ * @mixin Webpage
+ */
+trait HasTracing
+{
+    /**
+     * Starts tracing
+     */
+    public function startTracing(
+        bool $screenshots = true,
+        bool $snapshots = true,
+    ): self {
+        $this->page->context()->tracing()->start([
+            'screenshots' => $screenshots,
+            'snapshots' => $snapshots,
+        ]);
+        $this->page->context()->tracing()->startChunk();
+
+        return $this;
+    }
+
+    /**
+     * Stops tracing and saves artifact
+     */
+    public function stopTracing(?string $filename = null): self
+    {
+        $artifact = $this->page->context()->tracing()->stopChunk([
+            'mode' => 'archive',
+        ]);
+        $this->page->context()->tracing()->stop();
+
+        $artifact->saveAs(['path' => Tracing::path($filename)]);
+
+        return $this;
+    }
+}

src/Api/Webpage.php

@@ -11,7 +11,8 @@
 
 final readonly class Webpage
 {
-    use Concerns\HasWaitCapabilities,
+    use Concerns\HasTracing,
+        Concerns\HasWaitCapabilities,
         Concerns\InteractsWithElements,
         Concerns\InteractsWithFrames,
         Concerns\InteractsWithScreen,

src/Enums/TracingOption.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Browser\Enums;
+
+/**
+ * @internal
+ */
+enum TracingOption: string
+{
+    case OFF = 'off';
+    case ON = 'on';
+    case RETAIN_ON_FAILURE = 'retain-on-failure';
+}

src/Exceptions/TracingOptionNotSupportedException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Browser\Exceptions;
+
+use RuntimeException;
+
+/**
+ * @internal
+ */
+final class TracingOptionNotSupportedException extends RuntimeException
+{
+    //
+}

src/Filters/UsesBrowserTestCaseMethodFilter.php

@@ -5,6 +5,7 @@
 namespace Pest\Browser\Filters;
 
 use Pest\Browser\Playwright\Playwright;
+use Pest\Browser\Playwright\Tracing;
 use Pest\Browser\Plugin;
 use Pest\Browser\ServerManager;
 use Pest\Browser\Support\BrowserTestIdentifier;
@@ -59,6 +60,7 @@ public function accept(TestCaseMethodFactory $factory): bool
 
             ServerManager::instance()->playwright()->start();
             Screenshot::cleanup();
+            Tracing::cleanup();
         }
 
         return true;

src/Playwright/Artifact.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Browser\Playwright;
+
+/**
+ * @internal
+ */
+final readonly class Artifact
+{
+    use Concerns\InteractsWithPlaywright;
+
+    /**
+     * Creates a new context instance.
+     */
+    public function __construct(
+        private string $guid
+    ) {
+        //
+    }
+
+    /**
+     * Save artifact
+     *
+     * @param  array<string, mixed>  $params
+     */
+    public function saveAs(array $params = []): void
+    {
+        $response = Client::instance()->execute($this->guid, 'saveAs', $params);
+        $this->processVoidResponse($response);
+    }
+}

src/Playwright/Browser.php

@@ -4,6 +4,7 @@
 
 namespace Pest\Browser\Playwright;
 
+use Pest\Browser\Enums\TracingOption;
 use Pest\Browser\Exceptions\BrowserAlreadyClosedException;
 
 /**
@@ -47,15 +48,29 @@ public function newContext(array $options = []): Context
 
         $response = Client::instance()->execute($this->guid, 'newContext', $options);
 
-        /** @var array{result: array{context: array{guid: string|null}}} $message */
+        /** @var array{result: array{context: array{guid: string|null}}, params: array{type: string|null, guid: string}} $message */
         foreach ($response as $message) {
+            if (isset($message['params']['type']) && $message['params']['type'] === 'Tracing') {
+                $tracing = new Tracing($message['params']['guid']);
+            }
             if (isset($message['result']['context']['guid'])) {
-                $context = new Context($this, $message['result']['context']['guid']);
+                assert(isset($tracing), 'Tracing object was not initialized.');
+                $context = new Context($this, $tracing, $message['result']['context']['guid']);
             }
         }
 
+        assert(isset($tracing), 'Tracing object was not initialized.');
         assert(isset($context), 'Browser context was not created successfully.');
 
+        // Auto start tracing
+        if (Playwright::tracingOption() !== TracingOption::OFF) {
+            $tracing->start([
+                'screenshots' => true,
+                'snapshots' => true,
+            ]);
+            $tracing->startChunk();
+        }
+
         $this->contexts[] = $context;
 
         return $context;

src/Playwright/Context.php

@@ -23,6 +23,7 @@ final class Context
      */
     public function __construct(
         private readonly Browser $browser,
+        private readonly Tracing $tracing,
         private readonly string $guid
     ) {
         //
@@ -36,6 +37,14 @@ public function browser(): Browser
         return $this->browser;
     }
 
+    /**
+     * Gets the tracing instance.
+     */
+    public function tracing(): Tracing
+    {
+        return $this->tracing;
+    }
+
     /**
      * Creates a new page in the context.
      */
@@ -69,6 +78,8 @@ public function close(): void
             return;
         }
 
+        $this->tracing->close();
+
         try {
             // fix this...
             $response = $this->sendMessage('close');

src/Playwright/Playwright.php

@@ -6,6 +6,7 @@
 
 use Pest\Browser\Enums\BrowserType;
 use Pest\Browser\Enums\ColorScheme;
+use Pest\Browser\Enums\TracingOption;
 
 /**
  * @internal
@@ -34,6 +35,11 @@ final class Playwright
      */
     private static bool $shouldDiffOnScreenshotAssertions = false;
 
+    /**
+     * The tracing option.
+     */
+    private static TracingOption $tracingOption = TracingOption::OFF;
+
     /**
      * The default browser type.
      */
@@ -197,6 +203,22 @@ public static function reset(): void
         }
     }
 
+    /**
+     * Sets the default browser type.
+     */
+    public static function setTracingOption(TracingOption $tracingOption): void
+    {
+        self::$tracingOption = $tracingOption;
+    }
+
+    /**
+     * Get the default browser type.
+     */
+    public static function tracingOption(): TracingOption
+    {
+        return self::$tracingOption;
+    }
+
     /**
      * Sets the default browser type.
      */