test: add UI tests (#4)

* test: add UI tests

* Fix @nicolas-grekas' review

Author: dunglas

CONTRIBUTING.md

@@ -8,8 +8,19 @@ Start the test app:
     $ cd tests/app
     $ yarn encore dev --watch
 
-Convenient endpoints:
+## Convenient endpoints:
 
 * `http://localhost:8000`: basic features
 * `http://localhost:8000/chat`: chat using Turbo Streams
 * `http://localhost:8000/books`: broadcast
+
+## Run tests
+
+### PHP tests
+
+    php vendor/bin/simple-phpunit
+
+### JavaScript tests
+
+    cd Resources/assets
+    yarn test

README.md

@@ -1,6 +1,6 @@
 # Symfony UX Turbo
 
-Symfony UX Turbo a Symfony bundle integrating the [Hotwire Turbo](https://turbo.hotwire.dev)
+Symfony UX Turbo is a Symfony bundle integrating the [Hotwire Turbo](https://turbo.hotwire.dev)
 library in Symfony applications. It is part of [the Symfony UX initiative](https://symfony.com/ux).
 
 Symfony UX Turbo allow having the same user experience as with [Single Page Apps](https://en.wikipedia.org/wiki/Single-page_application)
@@ -105,6 +105,40 @@ class MyController
 }
 ```
 
+#### Writing Tests
+
+Under the hood, Symfony UX Turbo relies on JavaScript to update the HTML page.
+To test if your website works properly, you will have to write [UI tests](https://martinfowler.com/articles/practical-test-pyramid.html#UiTests).
+
+Fortunately, we've got you covered! [Symfony Panther](https://github.com/symfony/panther) is a convenient testing tool
+using real browsers to test your Symfony application. It shares the same API as BrowserKit, the functional testing tool shipped with Symfony.
+
+[Install Symfony Panther](https://github.com/symfony/panther#installing-panther), and write a test for our Turbo Frame:
+
+```php
+// tests/TurboFrameTest.php
+namespace App\Tests;
+
+use Symfony\Component\Panther\PantherTestCase;
+
+class TurboFrameTest extends PantherTestCase
+{
+    public function testFrame(): void
+    {
+        $client = self::createPantherClient();
+        $client->request('GET', '/');
+
+        $client->clickLink('This block is scoped, the rest of the page will not change if you click here!');
+        $this->assertSelectorTextContains('body', 'This will replace the content of the Turbo Frame!');
+    }
+}
+```
+
+Run `bin/phpunit` to execute the test! Symfony Panther automatically started your application with a web server
+and tested it using Google Chrome (Firefox is also supported)!
+
+You can even let Panther open Chrome, and see what happens: `PANTHER_NO_HEADLESS=1 bin/phpunit --debug`
+
 [Read the Turbo Frames documentation](https://turbo.hotwire.dev/handbook/frames) to learn everything you can do using Turbo Frames.
 
 ### Coming Alive with Turbo Streams
@@ -442,17 +476,9 @@ However, it is currently considered
 [**experimental**](https://symfony.com/doc/current/contributing/code/experimental.html),
 meaning it is not bound to Symfony's BC policy for the moment.
 
-## Run tests
+## Credits
 
-### PHP tests
+Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop).
 
-```sh
-php vendor/bin/simple-phpunit
-```
-
-### JavaScript tests
-
-```sh
-cd Resources/assets
-yarn test
-```
+Symfony UX Turbo has been inspired by [hotwired/turbo-rails](https://github.com/hotwired/turbo-rails)
+and [sroze/live-twig](https://github.com/sroze/live-twig).

composer.json

@@ -49,6 +49,7 @@
         "symfony/framework-bundle": "^4.4|^5.2",
         "symfony/mercure-bundle": "^0.2.6",
         "symfony/messenger": "^4.4|^5.2",
+        "symfony/panther": "^0.9",
         "symfony/phpunit-bridge": "^4.4|^5.2",
         "symfony/security-core": "5.x-dev",
         "symfony/stopwatch": "^4.4|^5.2",

phpunit.xml.dist

@@ -8,6 +8,14 @@
          failOnRisky="true"
          failOnWarning="true"
 >
+    <php>
+        <ini name="error_reporting" value="-1" />
+        <server name="APP_ENV" value="test" force="true" />
+        <server name="SHELL_VERBOSITY" value="-1" />
+        <server name="KERNEL_CLASS" value="App\Kernel" />
+        <server name="PANTHER_WEB_SERVER_DIR" value="./tests/app/public" />
+    </php>
+
     <testsuites>
         <testsuite name="Project Test Suite">
             <directory>tests</directory>
@@ -16,11 +24,15 @@
 
     <filter>
         <whitelist processUncoveredFilesFromWhitelist="true">
-            <directory suffix=".php">.</directory>
-            <exclude>
-                <directory>tests</directory>
-                <directory>vendor</directory>
-            </exclude>
+            <directory suffix=".php">src</directory>
         </whitelist>
     </filter>
+
+    <listeners>
+        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener" />
+    </listeners>
+
+    <extensions>
+        <extension class="Symfony\Component\Panther\ServerExtension" />
+    </extensions>
 </phpunit>

src/Twig/FrameExtension.php

@@ -25,6 +25,9 @@ final class FrameExtension extends AbstractExtension
 {
     public function getFunctions(): iterable
     {
+        yield new TwigFunction('render_turbo_frame', function (string $id, string $src, array $attrs = []): string {
+            return $this->turboFrameStart($id, $attrs + ['src' => $src]).$this->turboFrameEnd();
+        }, ['is_safe' => ['html']]);
         yield new TwigFunction('turbo_frame_start', [$this, 'turboFrameStart'], ['is_safe' => ['html']]);
         yield new TwigFunction('turbo_frame_end', [$this, 'turboFrameEnd'], ['is_safe' => ['html']]);
     }

tests/BroadcastTest.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Symfony UX Turbo package.
+ *
+ * (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\UX\Turbo\Tests;
+
+use Symfony\Component\Panther\PantherTestCase;
+
+/**
+ * BroadcastTest.
+ *
+ * @author Kévin Dunglas <[email protected]>
+ */
+class BroadcastTest extends PantherTestCase
+{
+    private const BOOK_TITLE = 'The Ecology of Freedom: The Emergence and Dissolution of Hierarchy';
+
+    public function testBroadcast(): void
+    {
+        ($client = self::createPantherClient())->request('GET', '/books');
+        $crawler = $client->submitForm('Submit', ['title' => self::BOOK_TITLE]);
+
+        $client->waitForElementToContain('#books', self::BOOK_TITLE);
+
+        if (!preg_match('/\(#([0-9]+)\)/', $crawler->filter('#books div')->text(), $matches)) {
+            $this->fail('ID not found');
+        }
+
+        $client->submitForm('Submit', ['id' => $matches[1], 'title' => 'updated']);
+        $client->waitForElementToContain('#books', 'updated');
+
+        $client->submitForm('Submit', ['id' => $matches[1], 'remove' => 'remove']);
+        $client->waitForElementToNotContain('#books', $matches[1]);
+
+        $this->assertTrue(true);
+    }
+}

tests/TurboFrameTest.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the Symfony UX Turbo package.
+ *
+ * (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\UX\Turbo\Tests;
+
+use Symfony\Component\Panther\PantherTestCase;
+
+/**
+ * @author Kévin Dunglas <[email protected]>
+ */
+class TurboFrameTest extends PantherTestCase
+{
+    public function testFrame(): void
+    {
+        ($client = self::createPantherClient())->request('GET', '/');
+
+        $client->clickLink('This block is scoped, the rest of the page will not change if you click here!');
+        $client->waitForElementToContain('body', 'This will replace the content of the Turbo Frame!');
+
+        $this->assertTrue(true);
+    }
+}

tests/TurboStreamTest.php

@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Symfony UX Turbo package.
+ *
+ * (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\UX\Turbo\Tests;
+
+use Symfony\Component\Panther\PantherTestCase;
+
+/**
+ * @author Kévin Dunglas <[email protected]>
+ */
+final class TurboStreamTest extends PantherTestCase
+{
+    public function testStream(): void
+    {
+        ($client = self::createPantherClient())->request('GET', '/');
+
+        $client->submitForm('Trigger Turbo Stream!');
+        $client->waitForElementToContain('body', 'This div replace the existing element with the DOM ID "form".');
+        $this->assertSelectorTextContains('body', 'This div replace the existing element with the DOM ID "form".');
+
+        $this->assertTrue(true);
+    }
+}