[#15428] Add a bit more detail to bootstrap article

Author: wouterj

testing.rst

@@ -8,6 +8,8 @@ Whenever you write a new line of code, you also potentially add new bugs.
 To build better and more reliable applications, you should test your code
 using both functional and unit tests.
 
+.. _testing-installation:
+
 The PHPUnit Testing Framework
 -----------------------------
 

testing/bootstrap.rst

@@ -6,47 +6,64 @@ running those tests. For example, if you're running a functional test and
 have introduced a new translation resource, then you will need to clear your
 cache before running those tests.
 
-To do this, first add a file that executes your bootstrap work::
+When :ref:`installing testing <testing-installation>` using Symfony Flex,
+it already created a ``tests/bootstrap.php`` file that is run by PHPUnit
+before your tests.
 
-    // tests/bootstrap.php
-    if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) {
-        // executes the "php bin/console cache:clear" command
-        passthru(sprintf(
-            'APP_ENV=%s php "%s/../bin/console" cache:clear --no-warmup',
-            $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'],
-            __DIR__
-        ));
-    }
+You can modify this file to add custom logic:
 
-    require __DIR__.'/../config/bootstrap.php';
+.. code-block:: diff
 
-Then, check that your ``phpunit.xml.dist`` file runs this ``bootstrap.php`` file
-before running the tests:
+      // tests/bootstrap.php
+      use Symfony\Component\Dotenv\Dotenv;
 
-.. code-block:: xml
+      require dirname(__DIR__).'/vendor/autoload.php';
 
-    <!-- phpunit.xml.dist -->
-    <?xml version="1.0" encoding="UTF-8" ?>
-    <phpunit
-        bootstrap="tests/bootstrap.php"
-    >
-        <!-- ... -->
-    </phpunit>
+      if (file_exists(dirname(__DIR__).'/config/bootstrap.php')) {
+          require dirname(__DIR__).'/config/bootstrap.php';
+      } elseif (method_exists(Dotenv::class, 'bootEnv')) {
+          (new Dotenv())->bootEnv(dirname(__DIR__).'/.env');
+      }
+
+    + if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) {
+    +     // executes the "php bin/console cache:clear" command
+    +     passthru(sprintf(
+    +         'APP_ENV=%s php "%s/../bin/console" cache:clear --no-warmup',
+    +         $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'],
+    +         __DIR__
+    +     ));
+    + }
+
+.. note::
 
-Now, you can define in your ``phpunit.xml.dist`` file which environment you want the
-cache to be cleared:
+    If you don't use Symfony Flex, make sure this file is configured as
+    bootstrap file in your ``phpunit.xml.dist`` file:
+
+    .. code-block:: xml
+
+        <!-- phpunit.xml.dist -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <phpunit
+            bootstrap="tests/bootstrap.php"
+        >
+            <!-- ... -->
+        </phpunit>
+
+Now, you can update the ``phpunit.xml.dist`` file to declare the custom
+environment variable introduced to ``tests/bootstrap.php``:
 
 .. code-block:: xml
 
     <!-- phpunit.xml.dist -->
     <?xml version="1.0" encoding="UTF-8" ?>
     <phpunit>
-        <!-- ... -->
-
         <php>
             <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test"/>
+            <!-- ... -->
         </php>
+
+        <!-- ... -->
     </phpunit>
 
-This now becomes an environment variable (i.e. ``$_ENV``) that's available
-in the custom bootstrap file (``tests/bootstrap.php``).
+Now, when running ``vendor/bin/phpunit``, the cache will be cleared
+automatically by the bootstrap file before running all tests.