[#1735] Tweaks to the new test cache-clearing entry

This was made a little bit more generic - and also includes some minor items

Author: weaverryan

cookbook/map.rst.inc

@@ -129,6 +129,7 @@
   * :doc:`/cookbook/testing/insulating_clients`
   * :doc:`/cookbook/testing/profiling`
   * :doc:`/cookbook/testing/doctrine`
+  * :doc:`/cookbook/testing/bootstrap`
 
 * :doc:`/cookbook/validation/index`
 

cookbook/testing/auto_cache_clear.rst

@@ -0,0 +1,41 @@
+How to customize the Bootstrap Process before running Tests
+===========================================================
+
+Sometimes when running tests, you need to do additional bootstrap work before
+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. This cookbook covers how to do that.
+
+First, add the following file::
+
+    // app/tests.bootstrap.php
+    if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) {
+        passthru(sprintf(
+            'php "%s/console" cache:clear --env=%s --no-warmup',
+            __DIR__,
+            $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV']
+        ));
+    }
+
+    require __DIR__.'/bootstrap.php.cache';
+
+Replace the test bootstrap file ``bootstrap.php.cache`` in ``app/phpunit.xml.dist``
+with ``tests.bootstrap.php``:
+
+.. code-block:: xml
+
+    <!-- app/phpunit.xml.dist -->
+    bootstrap = "tests.bootstrap.php"
+
+Now, you can define in your ``phpunit.xml.dist`` file which environment you want the
+cache to be cleared:
+
+.. code-block:: xml
+
+    <!-- app/phpunit.xml.dist -->
+    <php>
+        <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test"/>
+    </php>
+
+This now becomes an environment variable (i.e. ``$_ENV``) that's available
+in the custom bootstrap file (``tests.bootstrap.php``).

cookbook/testing/bootstrap.rst

@@ -8,3 +8,4 @@ Testing
     insulating_clients
     profiling
     doctrine
+    bootstrap