Add info about troubleshooting assets loading with Panther.

- Can happen with any requested uri that look like a non `.php` file - Case can happen with AssetMapper.
symfony · Oct 14, 2024 · 6a8cc6d · 6a8cc6d
1 parent 6c48614
commit 6a8cc6d
Showing 1 changed file with 104 additions and 0 deletions.
diff --git a/testing/end_to_end.rst b/testing/end_to_end.rst
@@ -799,6 +799,106 @@ variable to ``false`` in your style file:
 
     $enable-smooth-scroll: false;
 
+Assets not loading
+~~~~~~~~~~~~~~~~~~
+
+You may face cases where your assets are not loaded while running your tests.
+Because Panther use the `PHP built-in server`_ to serve your app, if your assets files
+(or any requested URI that not a ``.php`` file) does not exist in your public directory
+(e.g. rendered by your Symfony app), the built-in server will return a 404 not found.
+
+This can happen when using :doc:`AssetMapper component </frontend/asset_mapper>`
+if you let your Symfony app handle your assets in dev environment.
+
+To solve this, add a ``tests/router.php``::
+
+    // tests/router.php
+    if (is_file($_SERVER['DOCUMENT_ROOT'].\DIRECTORY_SEPARATOR.$_SERVER['SCRIPT_NAME'])) {
+        return false;
+    }
+
+    $script = 'index.php';
+
+    $_SERVER = array_merge($_SERVER, $_ENV);
+    $_SERVER['SCRIPT_FILENAME'] = $_SERVER['DOCUMENT_ROOT'].\DIRECTORY_SEPARATOR.$script;
+
+    $_SERVER['SCRIPT_NAME'] = \DIRECTORY_SEPARATOR.$script;
+    $_SERVER['PHP_SELF'] = \DIRECTORY_SEPARATOR.$script;
+
+    require $script;
+
+Then declare it as a router for Panther server in ``phpunit.xml.dist`` using ``PANTHER_WEB_SERVER_ROUTER`` var:
+
+.. code-block:: xml
+
+    <!-- phpunit.xml.dist -->
+    <phpunit>
+        <!-- ... -->
+        <php>
+            <!-- ... -->
+            <server name="PANTHER_WEB_SERVER_ROUTER" value="../tests/router.php"/>
+        </php>
+    </phpunit>
+
+Credit from `Testing Part 2 Functional Testing on Symfony cast`_ were you can see more about this case.
+
+.. note::
+
+    When using :doc:`AssetMapper component </frontend/asset_mapper>`, you can also compile your assets before running
+    your tests. It will make your tests faster because Symfony will not have to handle them, the built-in server
+    will serve them directly.
+
+
+Assets not loading
+~~~~~~~~~~~~~~~~~~
+
+You may face cases where your assets are not loaded while running your tests.
+Because Panther use the `PHP built-in server`_ to serve your app, if your assets files
+(or any requested URI that not a ``.php`` file) does not exist in your public directory
+(e.g. rendered by your Symfony app), the built-in server will return a 404 not found.
+
+This can happen when using :doc:`AssetMapper component </frontend/asset_mapper>`
+if you let your Symfony app handle your assets in dev environment.
+
+To solve this, add a ``tests/router.php``::
+
+    // tests/router.php
+    if (is_file($_SERVER['DOCUMENT_ROOT'].\DIRECTORY_SEPARATOR.$_SERVER['SCRIPT_NAME'])) {
+        return false;
+    }
+
+    $script = 'index.php';
+
+    $_SERVER = array_merge($_SERVER, $_ENV);
+    $_SERVER['SCRIPT_FILENAME'] = $_SERVER['DOCUMENT_ROOT'].\DIRECTORY_SEPARATOR.$script;
+
+    $_SERVER['SCRIPT_NAME'] = \DIRECTORY_SEPARATOR.$script;
+    $_SERVER['PHP_SELF'] = \DIRECTORY_SEPARATOR.$script;
+
+    require $script;
+
+Then declare it as a router for Panther server in ``phpunit.xml.dist`` using ``PANTHER_WEB_SERVER_ROUTER`` var:
+
+.. code-block:: xml
+
+    <!-- phpunit.xml.dist -->
+    <phpunit>
+        <!-- ... -->
+        <php>
+            <!-- ... -->
+            <server name="PANTHER_WEB_SERVER_ROUTER" value="../tests/router.php"/>
+        </php>
+    </phpunit>
+
+Credit from `Testing Part 2 Functional Testing on Symfony cast`_ were you can see more about this case.
+
+.. note::
+
+    When using :doc:`AssetMapper component </frontend/asset_mapper>`, you can also compile your assets before running
+    your tests. It will make your tests faster because Symfony will not have to handle them, the built-in server
+    will serve them directly.
+
+
 Additional Documentation
 ------------------------
 
@@ -825,3 +925,7 @@ documentation:
 .. _`Gitlab CI`: https://docs.gitlab.com/ee/ci/
 .. _`AppVeyor`: https://www.appveyor.com/
 .. _`LiipFunctionalTestBundle`: https://github.com/liip/LiipFunctionalTestBundle
+.. _`PHP built-in server`: https://www.php.net/manual/en/features.commandline.webserver.php
+.. _`Testing Part 2 Functional Testing on Symfony cast`: https://symfonycasts.com/screencast/last-stack/testing
+.. _`PHP built in server`: https://www.php.net/manual/en/features.commandline.webserver.php
+.. _`Testing Part 2 Functional Testing on Symfony cast`: https://symfonycasts.com/screencast/last-stack/testing