minor #2720 [Toolkit] Add functional tests to render all Kit components usage codes (from their documentation), with a snapshot system (Kocal)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[Toolkit] Add functional tests to render all Kit components usage codes (from their documentation), with a snapshot system

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Docs?         | no <!-- required for new features -->
| Issues        | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

<!--
Replace this notice by a description of your feature/bugfix.
This will help reviewers and should be a good start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - For new features, provide some code snippets to help understand usage.
 - Features and deprecations must be submitted against branch main.
 - Update/add documentation as required (we can help!)
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
 - Never break backward compatibility (see https://symfony.com/bc).
-->

This PR add snapshots testing for each Twig code blocks from `src/Toolkit/kits/**/docs/components/*.md`, to ensure that rendering is always good.

I don't think we will add visual testing, at least for now. Having snapshots tests and visual previews (on the website) feels convenient enough, but if someone has a super-simple solution, why not!)

I tagged the PR as a feature, not because the snapshots testing itself, but because I introduced a new service `KitContextRunner`. I needed something similar than the "hacks" from the website, but for tests.

Commits
-------

7fea71c [Toolkit] Remove checks layers for tales-from-a-dev/twig-tailwind-extra on PHP < 8.2, since it now supports PHP 8.1
1b1c545 [Toolkit] Pin symfony/phpunit-bridge to ^7.2 and phpunit to ^9.6.22
114a43f [Toolkit] Remove documentation about non-existant component AlertDialog (will be re-added later 😇)
1ce9d56 [Toolkit] Add functional tests to render all Kit components usage codes (from their documentation), with a snapshot system
4314322 [Toolkit] Introduce KitContextRunner, to run code in the context of a given Kit

Author: Kocal

src/Toolkit/composer.json

@@ -44,8 +44,12 @@
     "zenstruck/console-test": "^1.7",
     "symfony/http-client": "6.4|^7.0",
     "symfony/stopwatch": "^6.4|^7.0",
-    "symfony/phpunit-bridge": "^6.4|^7.0",
-    "vincentlanglet/twig-cs-fixer": "^3.5"
+    "symfony/phpunit-bridge": "^7.2",
+    "vincentlanglet/twig-cs-fixer": "^3.5",
+    "spatie/phpunit-snapshot-assertions": "^4.2.17",
+    "phpunit/phpunit": "^9.6.22",
+    "symfony/ux-icons": "^2.18",
+    "tales-from-a-dev/twig-tailwind-extra": "^0.4.0"
   },
   "bin": [
     "bin/ux-toolkit-kit-create",

src/Toolkit/config/services.php

@@ -13,6 +13,7 @@
 
 use Symfony\UX\Toolkit\Command\DebugKitCommand;
 use Symfony\UX\Toolkit\Command\InstallComponentCommand;
+use Symfony\UX\Toolkit\Kit\KitContextRunner;
 use Symfony\UX\Toolkit\Kit\KitFactory;
 use Symfony\UX\Toolkit\Kit\KitSynchronizer;
 use Symfony\UX\Toolkit\Registry\GitHubRegistry;
@@ -75,5 +76,12 @@
             ->args([
                 service('filesystem'),
             ])
+
+        ->set('ux_toolkit.kit.kit_context_runner', KitContextRunner::class)
+            ->public()
+            ->args([
+                service('twig'),
+                service('ux.twig_component.component_factory'),
+            ])
     ;
 };

src/Toolkit/kits/shadcn/docs/components/AlertDialog.md

@@ -4,16 +4,14 @@
       backupGlobals="false"
       colors="true"
       bootstrap="tests/bootstrap.php"
-      failOnRisky="true" 
+      failOnRisky="true"
       failOnWarning="true"
 >
   <php>
     <ini name="display_errors" value="1"/>
     <ini name="error_reporting" value="-1"/>
     <server name="APP_ENV" value="test" force="true"/>
     <server name="SHELL_VERBOSITY" value="-1"/>
-    <server name="SYMFONY_PHPUNIT_REMOVE" value=""/>
-    <server name="SYMFONY_PHPUNIT_VERSION" value="9.5"/>
     <server name="SYMFONY_DEPRECATIONS_HELPER" value="max[total]=999999"/>
     <server name="KERNEL_CLASS" value="Symfony\UX\Toolkit\Tests\Fixtures\Kernel"/>
   </php>

src/Toolkit/phpunit.xml.dist

@@ -0,0 +1,107 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Toolkit\Kit;
+
+use Symfony\Component\Filesystem\Path;
+use Symfony\UX\Toolkit\File\FileType;
+use Symfony\UX\TwigComponent\ComponentFactory;
+use Symfony\UX\TwigComponent\ComponentTemplateFinderInterface;
+use Twig\Loader\ChainLoader;
+use Twig\Loader\FilesystemLoader;
+
+/**
+ * @author Hugo Alliaume <[email protected]>
+ *
+ * @internal
+ */
+final class KitContextRunner
+{
+    public function __construct(
+        private readonly \Twig\Environment $twig,
+        private readonly ComponentFactory $componentFactory,
+    ) {
+    }
+
+    /**
+     * @template TResult of mixed
+     *
+     * @param callable(Kit): TResult $callback
+     *
+     * @return TResult
+     */
+    public function runForKit(Kit $kit, callable $callback): mixed
+    {
+        $resetServices = $this->contextualizeServicesForKit($kit);
+
+        try {
+            return $callback($kit);
+        } finally {
+            $resetServices();
+        }
+    }
+
+    /**
+     * @return callable(): void Reset the services when called
+     */
+    private function contextualizeServicesForKit(Kit $kit): callable
+    {
+        // Configure Twig
+        $initialTwigLoader = $this->twig->getLoader();
+        $this->twig->setLoader(new ChainLoader([
+            new FilesystemLoader(Path::join($kit->path, 'templates/components')),
+            $initialTwigLoader,
+        ]));
+
+        // Configure Twig Components
+        $reflComponentFactory = new \ReflectionClass($this->componentFactory);
+
+        $reflComponentFactoryConfig = $reflComponentFactory->getProperty('config');
+        $initialComponentFactoryConfig = $reflComponentFactoryConfig->getValue($this->componentFactory);
+        $reflComponentFactoryConfig->setValue($this->componentFactory, []);
+
+        $reflComponentFactoryComponentTemplateFinder = $reflComponentFactory->getProperty('componentTemplateFinder');
+        $initialComponentFactoryComponentTemplateFinder = $reflComponentFactoryComponentTemplateFinder->getValue($this->componentFactory);
+        $reflComponentFactoryComponentTemplateFinder->setValue($this->componentFactory, $this->createComponentTemplateFinder($kit));
+
+        return function () use ($initialTwigLoader, $reflComponentFactoryConfig, $initialComponentFactoryConfig, $reflComponentFactoryComponentTemplateFinder, $initialComponentFactoryComponentTemplateFinder) {
+            $this->twig->setLoader($initialTwigLoader);
+            $reflComponentFactoryConfig->setValue($this->componentFactory, $initialComponentFactoryConfig);
+            $reflComponentFactoryComponentTemplateFinder->setValue($this->componentFactory, $initialComponentFactoryComponentTemplateFinder);
+        };
+    }
+
+    private function createComponentTemplateFinder(Kit $kit): ComponentTemplateFinderInterface
+    {
+        static $instances = [];
+
+        return $instances[$kit->name] ?? new class($kit) implements ComponentTemplateFinderInterface {
+            public function __construct(private readonly Kit $kit)
+            {
+            }
+
+            public function findAnonymousComponentTemplate(string $name): ?string
+            {
+                if (null === $component = $this->kit->getComponent($name)) {
+                    throw new \RuntimeException(\sprintf('Component "%s" does not exist in kit "%s".', $name, $this->kit->name));
+                }
+
+                foreach ($component->files as $file) {
+                    if (FileType::Twig === $file->type) {
+                        return $file->relativePathName;
+                    }
+                }
+
+                throw new \LogicException(\sprintf('No Twig files found for component "%s" in kit "%s", it should not happens.', $name, $this->kit->name));
+            }
+        };
+    }
+}

src/Toolkit/src/Kit/KitContextRunner.php

@@ -16,8 +16,11 @@
 use Symfony\Bundle\TwigBundle\TwigBundle;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 use Symfony\Component\HttpKernel\Kernel as BaseKernel;
+use Symfony\UX\Icons\UXIconsBundle;
 use Symfony\UX\Toolkit\UXToolkitBundle;
 use Symfony\UX\TwigComponent\TwigComponentBundle;
+use TalesFromADev\Twig\Extra\Tailwind\Bridge\Symfony\Bundle\TalesFromADevTwigExtraTailwindBundle;
+use Twig\Extra\TwigExtraBundle\TwigExtraBundle;
 
 final class Kernel extends BaseKernel
 {
@@ -29,6 +32,9 @@ public function registerBundles(): iterable
             new FrameworkBundle(),
             new TwigBundle(),
             new TwigComponentBundle(),
+            new TwigExtraBundle(),
+            new UXIconsBundle(),
+            new TalesFromADevTwigExtraTailwindBundle(),
             new UXToolkitBundle(),
         ];
     }
@@ -69,6 +75,9 @@ protected function configureContainer(ContainerConfigurator $container): void
 
             ->alias('ux_toolkit.registry.registry_factory', '.ux_toolkit.registry.registry_factory')
                 ->public()
+
+            ->alias('ux_toolkit.registry.local', '.ux_toolkit.registry.local')
+                ->public()
         ;
     }
 }

src/Toolkit/tests/Fixtures/Kernel.php

@@ -0,0 +1,110 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\UX\Toolkit\Tests\Functional;
+
+use Spatie\Snapshots\Drivers\HtmlDriver;
+use Spatie\Snapshots\MatchesSnapshots;
+use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+use Symfony\Component\Filesystem\Path;
+use Symfony\Component\Finder\Finder;
+use Symfony\UX\Toolkit\Asset\Component;
+use Symfony\UX\Toolkit\Kit\Kit;
+use Symfony\UX\Toolkit\Kit\KitFactory;
+use Symfony\UX\Toolkit\Registry\LocalRegistry;
+
+class ComponentsRenderingTest extends WebTestCase
+{
+    use MatchesSnapshots;
+
+    private const KITS_DIR = __DIR__.'/../../kits';
+
+    /**
+     * @return iterable<string, string, string>
+     */
+    public static function provideTestComponentRendering(): iterable
+    {
+        foreach (LocalRegistry::getAvailableKitsName() as $kitName) {
+            $kitDir = Path::join(__DIR__, '../../kits', $kitName, 'docs/components');
+            $docsFinder = (new Finder())->files()->name('*.md')->in($kitDir)->depth(0);
+
+            foreach ($docsFinder as $docFile) {
+                $componentName = $docFile->getFilenameWithoutExtension();
+
+                $codeBlockMatchesResult = preg_match_all('/```twig.*?\n(?P<code>.+?)```/s', $docFile->getContents(), $codeBlockMatches);
+                if (false === $codeBlockMatchesResult || 0 === $codeBlockMatchesResult) {
+                    throw new \RuntimeException(\sprintf('No Twig code blocks found in file "%s"', $docFile->getRelativePathname()));
+                }
+
+                foreach ($codeBlockMatches['code'] as $i => $code) {
+                    yield \sprintf('Kit %s, component %s, code #%d', $kitName, $componentName, $i + 1) => [$kitName, $componentName, $code];
+                }
+            }
+        }
+    }
+
+    /**
+     * @dataProvider provideTestComponentRendering
+     */
+    public function testComponentRendering(string $kitName, string $componentName, string $code): void
+    {
+        $twig = self::getContainer()->get('twig');
+        $kitContextRunner = self::getContainer()->get('ux_toolkit.kit.kit_context_runner');
+
+        $kit = $this->instantiateKit($kitName);
+        $template = $twig->createTemplate($code);
+        $renderedCode = $kitContextRunner->runForKit($kit, fn () => $template->render());
+
+        $this->assertCodeRenderedMatchesHtmlSnapshot($kit, $kit->getComponent($componentName), $code, $renderedCode);
+    }
+
+    private function instantiateKit(string $kitName): Kit
+    {
+        $kitFactory = self::getContainer()->get('ux_toolkit.kit.kit_factory');
+
+        self::assertInstanceOf(KitFactory::class, $kitFactory);
+
+        return $kitFactory->createKitFromAbsolutePath(Path::join(__DIR__, '../../kits', $kitName));
+    }
+
+    private function assertCodeRenderedMatchesHtmlSnapshot(Kit $kit, Component $component, string $code, string $renderedCode): void
+    {
+        $info = \sprintf(<<<HTML
+            <!--
+            - Kit: %s
+            - Component: %s
+            - Code:
+            ```twig
+            %s
+            ```
+            - Rendered code (prettified for testing purposes, run "php vendor/bin/phpunit -d --update-snapshots" to update snapshots): -->
+            HTML,
+            $kit->name,
+            $component->name,
+            trim($code)
+        );
+
+        $this->assertMatchesSnapshot($renderedCode, new class($info) extends HtmlDriver {
+            public function __construct(private string $info)
+            {
+            }
+
+            public function serialize($data): string
+            {
+                $serialized = parent::serialize($data);
+                $serialized = str_replace(['<html><body>', '</body></html>'], '', $serialized);
+                $serialized = trim($serialized);
+
+                return $this->info."\n".$serialized;
+            }
+        });
+    }
+}