[Feature] Automatically take screenshot on failure/error (#392)

* add Client::takeScreenshot() test

* [feature] allow setting a base screenshot directory

* [feature] take screenshot on error/failure

* Update README.md

Co-authored-by: Kévin Dunglas <[email protected]>

* prepend the screenshot on error/failure with timestamp

* refactor saving screenshots on failure/error

- PantherTestCase::createPantherClient()/createAdditionalPantherClient() registers client with ServerExtension
- on failure/error, take screenshots for all instantiated clients in a test (primary and additional)

* Update README.md

Co-authored-by: Kévin Dunglas <[email protected]>

* ensure absolute path can always be used when taking screenshots

* simplify

Co-authored-by: Kévin Dunglas <[email protected]>

Author: kbond

.gitignore

@@ -4,6 +4,7 @@
 /composer.phar
 /composer.lock
 /phpunit.xml
+/screenshots/
 /vendor/
 /drivers/
 /screen.png

README.md

@@ -76,6 +76,10 @@ If you intend to use Panther to test your application, we strongly recommend reg
 While not strictly mandatory, this extension dramatically improves the testing experience by boosting the performance and
 allowing to use the [interactive debugging mode](#interactive-mode).
 
+When using the extension in conjunction with the `PANTHER_ERROR_SCREENSHOT_DIR` environment variable, tests using the
+Panther client that fail or error (after the client is created) will automatically get a screenshot taken to help
+debugging.
+
 To register the Panther extension, add the following lines to `phpunit.xml.dist`:
 
 ```xml
@@ -339,6 +343,7 @@ The following environment variables can be set to change some Panther's behaviou
 * `PANTHER_WEB_SERVER_ROUTER`:  to use a web server router script which is run at the start of each HTTP request
 * `PANTHER_EXTERNAL_BASE_URI`: to use an external web server (the PHP built-in web server will not be started)
 * `PANTHER_APP_ENV`: to override the `APP_ENV` variable passed to the web server running the PHP app
+* `PANTHER_ERROR_SCREENSHOT_DIR`: to set a base directory for your failure/error screenshots (e.g. `./screenshots`)
 
 ### Changing the Hostname and Port of the Built-in Web Server
 

src/PantherTestCaseTrait.php

@@ -186,6 +186,8 @@ protected static function createPantherClient(array $options = [], array $kernel
             static::bootKernel($kernelOptions); // @phpstan-ignore-line
         }
 
+        ServerExtension::registerClient(self::$pantherClient);
+
         return $callGetClient ? self::getClient(self::$pantherClient) : self::$pantherClient; // @phpstan-ignore-line
     }
 
@@ -198,7 +200,11 @@ protected static function createAdditionalPantherClient(): PantherClient
             return self::createPantherClient();
         }
 
-        return self::$pantherClients[] = self::$pantherClient = new PantherClient(self::$pantherClient->getBrowserManager(), self::$baseUri);
+        self::$pantherClients[] = self::$pantherClient = new PantherClient(self::$pantherClient->getBrowserManager(), self::$baseUri);
+
+        ServerExtension::registerClient(self::$pantherClient);
+
+        return self::$pantherClient;
     }
 
     /**

src/ServerExtension.php

@@ -16,17 +16,33 @@
 use PHPUnit\Runner\AfterLastTestHook;
 use PHPUnit\Runner\AfterTestErrorHook;
 use PHPUnit\Runner\AfterTestFailureHook;
+use PHPUnit\Runner\AfterTestHook;
 use PHPUnit\Runner\BeforeFirstTestHook;
+use PHPUnit\Runner\BeforeTestHook;
 
 /**
  *  @author Dany Maillard <[email protected]>
  */
-final class ServerExtension implements BeforeFirstTestHook, AfterLastTestHook, AfterTestErrorHook, AfterTestFailureHook
+final class ServerExtension implements BeforeFirstTestHook, AfterLastTestHook, BeforeTestHook, AfterTestHook, AfterTestErrorHook, AfterTestFailureHook
 {
     use ServerTrait;
 
+    /** @var bool */
+    private static $enabled = false;
+
+    /** @var Client[] */
+    private static $registeredClients = [];
+
+    public static function registerClient(Client $client): void
+    {
+        if (self::$enabled) {
+            self::$registeredClients[] = $client;
+        }
+    }
+
     public function executeBeforeFirstTest(): void
     {
+        self::$enabled = true;
         $this->keepServerOnTeardown();
     }
 
@@ -35,13 +51,46 @@ public function executeAfterLastTest(): void
         $this->stopWebServer();
     }
 
+    public function executeBeforeTest(string $test): void
+    {
+        self::reset();
+    }
+
+    public function executeAfterTest(string $test, float $time): void
+    {
+        self::reset();
+    }
+
     public function executeAfterTestError(string $test, string $message, float $time): void
     {
+        $this->takeScreenshots('error', $test);
         $this->pause(sprintf('Error: %s', $message));
     }
 
     public function executeAfterTestFailure(string $test, string $message, float $time): void
     {
+        $this->takeScreenshots('failure', $test);
         $this->pause(sprintf('Failure: %s', $message));
     }
+
+    private static function reset(): void
+    {
+        self::$registeredClients = [];
+    }
+
+    private function takeScreenshots(string $type, string $test): void
+    {
+        if (!($_SERVER['PANTHER_SCREENSHOT_DIR'] ?? false)) {
+            return;
+        }
+
+        foreach (self::$registeredClients as $i => $client) {
+            $client->takeScreenshot(sprintf('%s_%s_%s-%d.png',
+                (new \DateTime())->format('Y-m-d_H-i-s'),
+                $type,
+                strtr($test, ['\\' => '-', ':' => '_']),
+                $i
+            ));
+        }
+    }
 }

tests/ScreenshotTest.php

@@ -0,0 +1,53 @@
+<?php
+
+/*
+ * This file is part of the Panther project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Symfony\Component\Panther\Tests;
+
+use Symfony\Component\Filesystem\Filesystem;
+
+/**
+ * @author Kevin Bond <[email protected]>
+ */
+class ScreenshotTest extends TestCase
+{
+    private static $screenshotDir = __DIR__.'/../screenshots';
+    private static $screenshotFile = __DIR__.'/../screenshots/screenshot.jpg';
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        (new Filesystem())->remove(self::$screenshotDir);
+    }
+
+    public function testTakeScreenshot(): void
+    {
+        $client = self::createPantherClient();
+        $client->request('GET', '/basic.html');
+
+        $screen = $client->takeScreenshot();
+
+        $this->assertIsString($screen);
+    }
+
+    public function testTakeScreenshotAndSaveToFile(): void
+    {
+        $this->assertFileDoesNotExist(self::$screenshotFile);
+
+        $client = self::createPantherClient();
+        $client->request('GET', '/basic.html');
+        $client->takeScreenshot(self::$screenshotFile);
+
+        $this->assertFileExists(self::$screenshotFile);
+    }
+}