From 1e3138c29ab7905b9c7260c344be2ec43d2bcc23 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Mon, 1 Jun 2015 21:58:16 +0200 Subject: [PATCH] document the symfony test case --- doc/cache-invalidator.rst | 2 + doc/testing-your-application.rst | 86 ++++++++++++++++++++++++++------ src/Test/SymfonyTestCase.php | 7 +-- 3 files changed, 78 insertions(+), 17 deletions(-) diff --git a/doc/cache-invalidator.rst b/doc/cache-invalidator.rst index 4cea4c86..f83837b8 100644 --- a/doc/cache-invalidator.rst +++ b/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); diff --git a/doc/testing-your-application.rst b/doc/testing-your-application.rst index 8fa9db92..d7f77328 100644 --- a/doc/testing-your-application.rst +++ b/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,9 +72,9 @@ 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 @@ -76,7 +82,7 @@ Constant Getter Default ``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,9 +108,9 @@ 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 @@ -112,7 +118,7 @@ Constant Getter Default 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 ` 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 ----- diff --git a/src/Test/SymfonyTestCase.php b/src/Test/SymfonyTestCase.php index dbc9173f..5141f555 100644 --- a/src/Test/SymfonyTestCase.php +++ b/src/Test/SymfonyTestCase.php @@ -23,12 +23,13 @@ * * To define constants in the phpunit file, use this syntax: * - * + * * * - * 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 {