Allow keeping the webserver & client active even after test teardown (symfony#30)

* Add an opt-in listener to launch the server when test starts and stop it when suite stops

* Renamed old "Panthere" occurrences to "Panther"

* Fix feedback

* Added a test for the ServerListener

* CS fix & make "$stopServerOnTeardown" public

* Fix small typo in Readme

Author: Pierstoval

README.md

@@ -166,6 +166,24 @@ Unlike testing and web scraping libraries you're used to, Panther:
 * supports custom [Selenium server](https://www.seleniumhq.org) installations
 * supports remote browser testing services including [SauceLabs](https://saucelabs.com/) and [BrowserStack](https://www.browserstack.com/)
 
+### Using the `ServerListener` to Always Have a Running Web Server
+
+When you use the Panther client, the web server running in background will be started at runtime and stopped at test's
+teardown.
+
+If you want to improve performances and launch the server at PHPUnit startup, you can add the `ServerListener` to
+your PHPUnit configuration:
+
+```xml
+<!-- phpunit.xml.dist -->
+
+    <listeners>
+        <listener class="Symfony\Component\Panther\ServerListener" />
+    </listeners>
+```
+
+The listener will start the webserver when the test suite is started, and will stop it when all your tests are executed.
+
 ## Documentation
 
 Since Panther implements the API of popular libraries, it already has an extensive documentation:

src/PantherTestCaseTrait.php

@@ -26,6 +26,11 @@
  */
 trait PantherTestCaseTrait
 {
+    /**
+     * @var bool
+     */
+    public static $stopServerOnTeardown = true;
+
     /**
      * @var string|null
      */
@@ -52,6 +57,13 @@ trait PantherTestCaseTrait
     protected static $pantherClient;
 
     public static function tearDownAfterClass()
+    {
+        if (true === self::$stopServerOnTeardown) {
+            static::stopWebServer();
+        }
+    }
+
+    public static function stopWebServer()
     {
         if (null !== self::$webServerManager) {
             self::$webServerManager->quit();
@@ -70,7 +82,7 @@ public static function tearDownAfterClass()
         self::$baseUri = null;
     }
 
-    protected static function startWebServer(?string $webServerDir = null, string $hostname = '127.0.0.1', int $port = 9000): void
+    public static function startWebServer(?string $webServerDir = null, string $hostname = '127.0.0.1', int $port = 9000): void
     {
         if (null !== static::$webServerManager) {
             return;

src/ServerListener.php

@@ -0,0 +1,36 @@
+<?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;
+
+use PHPUnit\Framework\TestListener;
+use PHPUnit\Framework\TestListenerDefaultImplementation;
+use PHPUnit\Framework\TestSuite;
+
+final class ServerListener implements TestListener
+{
+    use TestListenerDefaultImplementation;
+
+    public function startTestSuite(TestSuite $suite): void
+    {
+        echo "Starting Panther server for test suite {$suite->getName()}...\n";
+        PantherTestCaseTrait::$stopServerOnTeardown = true;
+        PantherTestCaseTrait::startWebServer();
+    }
+
+    public function endTestSuite(TestSuite $suite): void
+    {
+        echo "\nShutting down Panther server...\n";
+        PantherTestCaseTrait::stopWebServer();
+    }
+}

tests/ServerListenerTest.php

@@ -0,0 +1,59 @@
+<?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 PHPUnit\Framework\TestSuite;
+use Symfony\Component\Panther\ServerListener;
+
+class ServerListenerTest extends TestCase
+{
+    private function createTestSuite()
+    {
+        $suite = $this->createMock(TestSuite::class);
+        $suite->expects($this->once())->method('getName')->willReturn('Dummy test suite');
+
+        return $suite;
+    }
+
+    public function testStartAndStop(): void
+    {
+        $this->expectOutputString("Starting Panther server for test suite Dummy test suite...\n\nShutting down Panther server...\n");
+
+        $_SERVER['PANTHER_WEB_SERVER_DIR'] = static::$webServerDir;
+
+        $streamContext = stream_context_create(['http' => [
+            'ignore_errors' => true,
+            'protocol_version' => '1.1',
+            'header' => ['Connection: close'],
+            'timeout' => 1,
+        ]]);
+
+        $healthCheck = function () use ($streamContext) {
+            return @file_get_contents('http://127.0.0.1:9000', false, $streamContext);
+        };
+
+        $testSuite = $this->createTestSuite();
+
+        $listener = new ServerListener();
+        $listener->startTestSuite($testSuite);
+
+        // Means the server rendered a 404, so server is running.
+        static::assertContains('<title>404 Not Found</title>', $healthCheck());
+
+        $listener->endTestSuite($testSuite);
+
+        // False means that ping failed.
+        static::assertFalse($healthCheck());
+    }
+}