minor #20316 [AssetMapper] Add info about troubleshooting assets load…

…ing with Panther. (WedgeSama)

This PR was merged into the 6.4 branch.

Discussion
----------

[AssetMapper] Add info about troubleshooting assets loading with Panther.

Add more info on Panther tests due to PHP built in server.

When a requested URI is not a `.php` file nor a directory, the built in server will try to directly server the corresponding "file". But if the file does not exist AND must be handle by Symfony app, the built in server just return a 404.

- Can happen with any requested URI that look like a non `.php` file
- Case can happen with AssetMapper.

see
symfony/panther#630
https://symfonycasts.com/screencast/last-stack/testing#debugging-by-opening-the-browser
https://www.php.net/manual/en/features.commandline.webserver.php

Commits
-------

f2a68b5 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.

testing/end_to_end.rst

@@ -799,6 +799,55 @@ variable to ``false`` in your style file:
 
     $enable-smooth-scroll: false;
 
+Assets not loading (PHP built-in server only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 +874,5 @@ 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