document the symfony test case

Author: dbu

doc/cache-invalidator.rst

@@ -17,6 +17,8 @@ Create the cache invalidator by passing a proxy client as
  $client = new ProxyClient\Varnish(...);
  // or
  $client = new ProxyClient\Nginx(...);
+ // or
+ $client = new ProxyClient\Symfony(...);
 
  $cacheInvalidator = new CacheInvalidator($client);
 

doc/testing-your-application.rst

@@ -3,12 +3,11 @@
 Testing Your Application
 ========================
 
-This chapter describes how to test your application against your reverse proxy
-instance.
+This chapter describes how to test your application against your reverse proxy.
 
 The FOSHttpCache library provides base test case classes to help you write
-functional tests. This may be helpful to test the way your application sets
-caching headers and invalidates cached content.
+functional tests. This is helpful to test the way your application sets caching
+headers and invalidates cached content.
 
 By having your test classes extend one of the test case classes, you get:
 
@@ -18,10 +17,17 @@ By having your test classes extend one of the test case classes, you get:
  reverse proxy server. See reverse proxy specific sections for details;
 * convenience methods for executing HTTP requests to your application:
  ``$this->getHttpClient()`` and ``$this->getResponse()``;
-* custom assertions ``assertHit`` and ``assertMiss`` for validating a cache hit/miss.
+* custom assertions ``assertHit`` and ``assertMiss`` for validating a cache
+ hit/miss.
 
 The recommended way to configure the test case is by setting constants
-in your `phpunit.xml`. Alternatively, you can override the getter methods.
+in your ``phpunit.xml``. Alternatively, you can override the getter methods.
+
+You will need to run a web server to provide the PHP application you want to
+test. The test cases only handle running the caching proxy. With PHP 5.4 or
+newer, the easiest is to use the PHP built in web server. See the
+``WebServerListener`` class in ``tests/Functional`` and how it is registered in
+``phpunit.xml.dist``.
 
 Setting Constants
 ~~~~~~~~~~~~~~~~~
@@ -66,17 +72,17 @@ Make sure ``symfony/process`` is available in your project:
 Then set your Varnish configuration (VCL) file. All available configuration
 parameters are shown below.
 
-======================= ========================= ================================================== ============================================
+======================= ========================= ================================================== ===========================================
 Constant Getter Default Description
-======================= ========================= ================================================== ============================================
+======================= ========================= ================================================== ===========================================
 ``VARNISH_FILE`` ``getConfigFile()`` your Varnish configuration (VCL) file
 ``VARNISH_BINARY`` ``getBinary()`` ``varnishd`` your Varnish binary
 ``VARNISH_PORT`` ``getCachingProxyPort()`` ``6181`` port Varnish listens on
 ``VARNISH_MGMT_PORT`` ``getVarnishMgmtPort()`` ``6182`` Varnish management port
 ``VARNISH_CACHE_DIR`` ``getCacheDir()`` ``sys_get_temp_dir()`` + ``/foshttpcache-varnish`` directory to use for cache
 ``VARNISH_VERSION`` ``getVarnishVersion()`` ``3`` installed varnish application version
 ``WEB_SERVER_HOSTNAME`` ``getHostName()`` hostname your application can be reached at
-======================= ========================= ================================================== ============================================
+======================= ========================= ================================================== ===========================================
 
 Enable Assertions
 '''''''''''''''''
@@ -91,8 +97,8 @@ NginxTestCase
 Configuration
 '''''''''''''
 
-By default, the ``NginxTestCase`` starts and stops the NGINX server for you and 
-deletes all cached contents. Make sure ``symfony/process`` is available in your 
+By default, the ``NginxTestCase`` starts and stops the NGINX server for you and
+deletes all cached contents. Make sure ``symfony/process`` is available in your
 project:
 
 .. code-block:: bash
@@ -102,17 +108,17 @@ project:
 You have to set your NGINX configuration file. All available configuration
 parameters are shown below.
 
-======================= ========================= ================================================ ==========================================
+======================= ========================= ================================================ ===========================================
 Constant Getter Default Description
-======================= ========================= ================================================ ==========================================
+======================= ========================= ================================================ ===========================================
 ``NGINX_FILE`` ``getConfigFile()`` your NGINX configuration file
 ``NGINX_BINARY`` ``getBinary()`` ``nginx`` your NGINX binary
 ``NGINX_PORT`` ``getCachingProxyPort()`` ``8088`` port NGINX listens on
 ``NGINX_CACHE_PATH`` ``getCacheDir()`` ``sys_get_temp_dir()`` + ``/foshttpcache-nginx`` directory to use for cache
  Must match `proxy_cache_path` directive in
  your configuration file.
 ``WEB_SERVER_HOSTNAME`` ``getHostName()`` hostname your application can be reached at
-======================= ========================= ================================================ ==========================================
+======================= ========================= ================================================ ===========================================
 
 Enable Assertions
 '''''''''''''''''
@@ -121,6 +127,58 @@ For the `assertHit` and `assertMiss` assertions to work, you need to add a
 :ref:`custom X-Cache header <nginx_debugging>` to responses served
 by your Nginx.
 
+SymfonyTestCase
+---------------
+
+This test case helps to test invalidation requests with a symfony application
+running the Symfony HttpCache and invalidating its cache folder to get reliable
+tests.
+
+The ``SymfonyTestCase`` does automatically start a web server. It is assumed
+that the web server you run for the application has the HttpCache integrated.
+
+Configuration
+'''''''''''''
+
+======================= ========================= ================================================ ===========================================
+Constant Getter Default Description
+======================= ========================= ================================================ ===========================================
+``WEB_SERVER_HOSTNAME`` ``getHostName()`` hostname your application can be reached at
+``WEB_SERVER_PORT`` ``getConfigFile()`` The port on which the web server runs
+``SYMFONY_CACHE_DIR`` ``getCacheDir()`` ``sys_get_temp_dir()`` + ``/foshttpcache-nginx`` directory to use for cache
+ Must match the configuration of your
+ HttpCache and must be writable by the user
+ running PHPUnit.
+======================= ========================= ================================================ ===========================================
+
+Enable Assertions
+'''''''''''''''''
+
+For the `assertHit` and `assertMiss` assertions to work, you need to add debug
+information in your AppCache. Create the cache kernel with the option
+``'debug' => true`` and add the following to your ``AppCache``::
+
+ public function handle(Request $request, $type = HttpKernelInterface::MASTER_REQUEST, $catch = true)
+ {
+ $response = parent::handle($request, $type, $catch);
+
+ if ($response->headers->has('X-Symfony-Cache')) {
+ if (false !== strpos($response->headers->get('X-Symfony-Cache'), 'miss')) {
+ $state = 'MISS';
+ } elseif (false !== strpos($response->headers->get('X-Symfony-Cache'), 'fresh')) {
+ $state = 'HIT';
+ } else {
+ $state = 'UNDETERMINED';
+ }
+ $response->headers->set('X-Cache', $state);
+ }
+
+ return $response;
+ }
+
+The ``UNDETERMINED`` state should never happen. If it does, it means that your
+HttpCache is not correctly set into debug mode.
+
 Usage
 -----
 

src/Test/SymfonyTestCase.php

@@ -23,12 +23,13 @@
  *
  * To define constants in the phpunit file, use this syntax:
  * <php>
- * <const name="WEB_SERVER_PORT" value="/tmp/foo" />
+ * <const name="WEB_SERVER_PORT" value="8080" />
  * </php>
  *
- * WEB_SERVER_PORT port the PHP webserver listens on (default 8080)
+ * WEB_SERVER_PORT port the PHP webserver listens on (required)
+ * WEB_SERVER_HOSTNAME hostname where your application can be reached (required)
  *
- * Note that the SymfonyProxy also defines a SYMFONY_CACHE_DIR constant.
+ * Note that the SymfonyProxy also uses a SYMFONY_CACHE_DIR constant.
  */
 abstract class SymfonyTestCase extends ProxyTestCase
 {