From 76730dea1f471cb521ef3ba2f6830aac048d13df Mon Sep 17 00:00:00 2001
From: Emaad Ali <emaadali@users.noreply.github.com>
Date: Mon, 22 Jun 2026 07:44:50 -0400
Subject: [PATCH] Add configurable screenshot directory

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 src/Configuration.php                         | 11 ++++
 src/Support/Screenshot.php                    | 17 +++++
 .../Configuration/HostConfigurationTest.php   | 22 +++++++
 tests/Unit/Support/ScreenshotTest.php         | 64 +++++++++++++++++++
 4 files changed, 114 insertions(+)

diff --git a/src/Configuration.php b/src/Configuration.php
index bf3c458f..36e44f66 100644
--- a/src/Configuration.php
+++ b/src/Configuration.php
@@ -7,6 +7,7 @@
 use Pest\Browser\Enums\BrowserType;
 use Pest\Browser\Enums\ColorScheme;
 use Pest\Browser\Playwright\Playwright;
+use Pest\Browser\Support\Screenshot;
 
 /**
  * @internal
@@ -95,6 +96,16 @@ public function userAgent(string $userAgent): self
         return $this;
     }
 
+    /**
+     * Sets the screenshots directory.
+     */
+    public function screenshots(string $dir): self
+    {
+        Screenshot::useDirectory($dir);
+
+        return $this;
+    }
+
     /**
      * Sets the host for the server.
      */
diff --git a/src/Support/Screenshot.php b/src/Support/Screenshot.php
index 57b9e996..ede161db 100644
--- a/src/Support/Screenshot.php
+++ b/src/Support/Screenshot.php
@@ -11,11 +11,28 @@
  */
 final class Screenshot
 {
+    /**
+     * The path to the screenshots' directory.
+     */
+    private static ?string $dir = null;
+
+    /**
+     * Set the path to the screenshots' directory.
+     */
+    public static function useDirectory(string $dir): void
+    {
+        self::$dir = $dir;
+    }
+
     /**
      * Return the path to the screenshots' directory.
      */
     public static function dir(): string
     {
+        if (self::$dir !== null) {
+            return self::$dir;
+        }
+
         return TestSuite::getInstance()->rootPath
             .'/tests/Browser/Screenshots';
     }
diff --git a/tests/Unit/Configuration/HostConfigurationTest.php b/tests/Unit/Configuration/HostConfigurationTest.php
index a6797ad6..0aa6b896 100644
--- a/tests/Unit/Configuration/HostConfigurationTest.php
+++ b/tests/Unit/Configuration/HostConfigurationTest.php
@@ -4,10 +4,22 @@
 
 use Pest\Browser\Configuration;
 use Pest\Browser\Playwright\Playwright;
+use Pest\Browser\Support\Screenshot;
+
+function resetConfigurationScreenshotDir(): void
+{
+    $property = new ReflectionProperty(Screenshot::class, 'dir');
+    $property->setValue(null, null);
+}
 
 beforeEach(function (): void {
     // Reset Playwright state before each test
     Playwright::setHost(null);
+    resetConfigurationScreenshotDir();
+});
+
+afterEach(function (): void {
+    resetConfigurationScreenshotDir();
 });
 
 it('can set host via configuration', function (): void {
@@ -31,6 +43,16 @@
     expect(Playwright::host())->toBe('app.localhost');
 });
 
+it('can set screenshots directory via configuration', function (): void {
+    $config = new Configuration();
+    $dir = sys_get_temp_dir().'/pest-browser-configuration-'.uniqid('', true);
+
+    $result = $config->screenshots($dir);
+
+    expect($result)->toBeInstanceOf(Configuration::class)
+        ->and(Screenshot::dir())->toBe($dir);
+});
+
 it('stores host in Playwright global state', function (): void {
     expect(Playwright::host())->toBeNull();
 
diff --git a/tests/Unit/Support/ScreenshotTest.php b/tests/Unit/Support/ScreenshotTest.php
index 3565da73..aeb363cd 100644
--- a/tests/Unit/Support/ScreenshotTest.php
+++ b/tests/Unit/Support/ScreenshotTest.php
@@ -3,6 +3,70 @@
 declare(strict_types=1);
 
 use Pest\Browser\Support\Screenshot;
+use Pest\TestSuite;
+
+function resetScreenshotDir(): void
+{
+    $property = new ReflectionProperty(Screenshot::class, 'dir');
+    $property->setValue(null, null);
+}
+
+function screenshotTestDir(string $name): string
+{
+    return sys_get_temp_dir().'/pest-browser-'.$name.'-'.uniqid('', true);
+}
+
+beforeEach(function (): void {
+    resetScreenshotDir();
+});
+
+afterEach(function (): void {
+    Screenshot::cleanup();
+    resetScreenshotDir();
+});
+
+it('uses the default screenshots directory', function (): void {
+    expect(Screenshot::dir())->toBe(TestSuite::getInstance()->rootPath.'/tests/Browser/Screenshots');
+});
+
+it('uses a configured screenshots directory', function (): void {
+    $dir = screenshotTestDir('configured');
+
+    Screenshot::useDirectory($dir);
+
+    expect(Screenshot::dir())->toBe($dir);
+});
+
+it('builds screenshot paths from the configured directory', function (): void {
+    $dir = screenshotTestDir('path');
+
+    Screenshot::useDirectory($dir);
+
+    expect(Screenshot::path('foo'))->toBe($dir.'/foo.png');
+});
+
+it('cleans up only the configured screenshots directory', function (): void {
+    $parent = screenshotTestDir('cleanup');
+    $dir = $parent.'/Screenshots';
+    $sharedFile = $parent.'/shared.txt';
+
+    mkdir($dir.'/Sliders', 0755, true);
+    mkdir($dir.'/ImageDiffView', 0755, true);
+    file_put_contents($dir.'/screenshot.png', 'screenshot');
+    file_put_contents($dir.'/Sliders/slider.png', 'slider');
+    file_put_contents($dir.'/ImageDiffView/diff.html', 'diff');
+    file_put_contents($sharedFile, 'shared');
+
+    Screenshot::useDirectory($dir);
+    Screenshot::cleanup();
+
+    expect(is_dir($dir))->toBeFalse()
+        ->and(is_dir($parent))->toBeTrue()
+        ->and(file_exists($sharedFile))->toBeTrue();
+
+    @unlink($sharedFile);
+    @rmdir($parent);
+});
 
 it('places screenshots under tests/Browser/screenshots', function (): void {
     Screenshot::save('asdf', 'test-screenshot.png');