Provide test functionality in traits

Fix #202.

separate http client from trait

Make property and methods private

Add traits to docs

Author: ddeboer

doc/includes/symfony-process.rst

@@ -0,0 +1,6 @@
+Requires Symfony’s Process component, so make sure to include that in your
+project:
+
+.. code-block:: bash
+
+    $ composer require symfony/process

doc/proxy-clients.rst

@@ -66,6 +66,8 @@ Then pass that adapter to the caching proxy client::
     $proxyClient = new Varnish($servers, '/baseUrl', $adapter);
     // Varnish as example, but also possible for NGINX and Symfony
 
+.. _varnish client:
+
 Varnish Client
 ~~~~~~~~~~~~~~
 

doc/symfony-cache-configuration.rst

@@ -179,4 +179,34 @@ the ``session_name_prefix`` option) in the requests to the backend. If you need
 a different behavior, overwrite ``UserContextSubscriber::cleanupHashLookupRequest``
 with your own logic.
 
+.. _symfony-cache x-debugging:
+
+Debugging
+~~~~~~~~~
+
+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.
+
 .. _HttpCache: http://symfony.com/doc/current/book/http_cache.html#symfony-reverse-proxy

doc/testing-your-application.rst

@@ -4,22 +4,30 @@ Testing Your Application
 ========================
 
 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 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:
-
-* independent tests: all previously cached content is removed in the tests
-  ``setUp`` method. The way this is done depends on which reverse proxy you use;
-* an instance of this library’s client that is configured to talk to your
-  reverse proxy server. See reverse proxy specific sections for details;
-* convenience methods for executing HTTP requests to your application:
-  ``$this->getHttpAdapter()`` and ``$this->getResponse()``;
-* custom assertions ``assertHit`` and ``assertMiss`` for validating a cache
+By running your tests against a live instance of your caching proxy, you can
+validate the caching headers that your application sets, and the invalidation
+rules that it defines.
+
+The FOSHttpCache library provides traits and base test classes to help you write
+functional tests. Using the traits, you can extend your own (or your
+framework’s) base test classes. For convenience, you can also extend the
+FOSHttpCache base test classes, as they include a sensible set of traits by
+default.
+
+By using the traits, you get:
+
+* independent tests: all previously cached content is removed in the test’s
+  ``setUp()`` method;
+* an instance of this library’s proxy client that is configured to talk to your
+  proxy server for invalidation requests;
+* a convenience method for executing HTTP requests to your caching proxy:
+  ``$this->getResponse()``;
+* custom assertions ``assertHit()`` and ``assertMiss()`` for validating a cache
   hit/miss.
 
+Configuration
+-------------
+
 The recommended way to configure the test case is by setting constants
 in your ``phpunit.xml``. Alternatively, you can override the getter methods.
 
@@ -56,89 +64,69 @@ You can override getters in your test class in the following way::
         }
     }
 
-VarnishTestCase
----------------
+Traits
+------
 
-Configuration
-'''''''''''''
+Caching Proxy Server Traits
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+FOSHttpCache provides three caching proxy traits that:
+
+* if necessary, start your caching proxy server before running the tests;
+* clear any cached content between tests to guarantee test isolation;
+* if necessary, stop the caching proxy server after the tests have finished;
+* provide ``getProxyClient()``, which returns the right
+  :doc:`proxy client <proxy-clients>` for your proxy server.
 
-By default, the ``VarnishTestCase`` starts and stops a Varnish server for you.
-Make sure ``symfony/process`` is available in your project:
+You only need to include one of these traits in your test classes. Which one
+you need (``VarnishTest``, ``NginxTest`` or ``SymfonyTest``) depends on the
+caching proxy server that you use.
 
-.. code-block:: bash
+VarnishTest Trait
+"""""""""""""""""
 
-    $ composer require symfony/process
+.. include:: includes/symfony-process.rst
 
-Then set your Varnish configuration (VCL) file. All available configuration
-parameters are shown below.
+Then configure the following parameters. The web server hostname and path to
+your VCL file are required.
 
 ======================= ========================= ================================================== ===========================================
 Constant                Getter                    Default                                            Description
 ======================= ========================= ================================================== ===========================================
+``WEB_SERVER_HOSTNAME`` ``getHostName()``                                                            hostname your application can be reached at
 ``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()``   ``4``                                              installed varnish application version
-``WEB_SERVER_HOSTNAME`` ``getHostName()``                                                            hostname your application can be reached at
 ======================= ========================= ================================================== ===========================================
 
-Enable Assertions
-'''''''''''''''''
-
-For the `assertHit` and `assertMiss` assertions to work, you need to add a
-:ref:`custom X-Cache header <varnish_debugging>` to responses served
-by your Varnish.
+NginxTest Trait
+"""""""""""""""
 
-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
-project:
-
-.. code-block:: bash
-
-    $ composer require symfony/process
+.. include:: includes/symfony-process.rst
 
-You have to set your NGINX configuration file. All available configuration
-parameters are shown below.
+Then configure the following parameters. The web server hostname and path to
+your NGINX configuration file are required.
 
 ======================= ========================= ================================================ ===========================================
 Constant                Getter                    Default                                          Description
 ======================= ========================= ================================================ ===========================================
+``WEB_SERVER_HOSTNAME`` ``getHostName()``                                                          hostname your application can be reached at
 ``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
-'''''''''''''''''
-
-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.
+SymfonyTest Trait
+"""""""""""""""""
 
-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
-'''''''''''''
+It is assumed that the web server you run for the application has the HttpCache
+integrated.
 
 ======================= ========================= ================================================ ===========================================
 Constant                Getter                    Default                                          Description
@@ -151,59 +139,92 @@ Constant                Getter                    Default
                                                                                                    running PHPUnit.
 ======================= ========================= ================================================ ===========================================
 
-Enable Assertions
-'''''''''''''''''
+HttpCaller Trait
+~~~~~~~~~~~~~~~~
+
+Provides your tests with a ``getResponse`` method, which retrieves a URI from
+your application through a real HTTP call that goes through the HTTP caching
+proxy::
 
-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``::
+    use FOS\HttpCache\Test\HttpCaller;
 
-    public function handle(Request $request, $type = HttpKernelInterface::MASTER_REQUEST, $catch = true)
+    class YourTest extends \PHPUnit_Framework_TestCase
     {
-        $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);
+        public function testCachingHeaders()
+        {
+            // Get some response from your application
+            $response = $this->getResponse('/path');
+
+            // Optionally with request headers and a custom  method
+            $response = $this->getResponse('/path', ['Accept' => 'text/json'], 'PUT');
         }
+    }
 
-        return $response;
+CacheAssertions Trait
+~~~~~~~~~~~~~~~~~~~~~
+
+Provides cache hit/miss assertions to your tests. To enable the these
+``assertHit`` and ``assertMiss`` assertions, you need to configure your caching
+server to set an `X-Cache` header with the cache status:
+
+* :ref:`Varnish <varnish_debugging>`
+* :ref:`NGINX <nginx_debugging>`
+* :ref:`Symfony HttpCache <symfony-cache x-debugging>`
+
+Then use the assertions as follows::
+
+    use FOS\HttpCache\Test\CacheAssertions;
+
+    class YourTest extends \PHPUnit_Framework_TestCase
+    {
+        public function testCacheHitOrMiss()
+        {
+            // Assert the application response is a cache miss
+            $this->assertMiss($response);
+
+            // Or assert it is a hit
+            $this->assertHit($response);
+        }
     }
 
-The ``UNDETERMINED`` state should never happen. If it does, it means that your
-HttpCache is not correctly set into debug mode.
+Base Classes for Convenience
+----------------------------
+
+If you prefer, you can extend your test classes from ``VarnishTestCase``,
+``NginxTestCase`` or ``SymfonyTestCase``. The appropriate traits will then
+automatically be included.
 
 Usage
 -----
 
 This example shows how you can test whether the caching headers your
-application sets influence Varnish as you expect them to::
+application sets influence your caching proxy as you expect them to::
 
-    use FOS\HttpCache\Test\VarnishTestCase;
+    use FOS\HttpCache\Test\CacheAssertions;
+    use FOS\HttpCache\Test\HttpCaller;
+    use FOS\HttpCache\Test\VarnishTest;
+    // or FOS\HttpCache\Test\NginxTest;
+    // or FOS\HttpCache\Test\SymfonyTest;
 
-    class YourFunctionalTest extends VarnishTestCase
+    class YourTest extends \PHPUnit_Framework_TestCase
     {
         public function testCachingHeaders()
         {
-            // Varnish is restarted, so you don’t have to worry about previously
-            // cached content. Before continuing, the VarnishTestCase waits for
-            // Varnish to become available.
+            // The caching proxy is (re)started, so you don’t have to worry
+            // about  previously cached content. Before continuing, the
+            // VarnishTest/ NginxTest trait waits for the caching proxy to
+            // become available.
 
-            // Retrieve an URL from your application
+            // Retrieve a URL from your application
             $response = $this->getResponse('/your/resource');
 
             // Assert the response was a cache miss (came from the backend
             // application)
             $this->assertMiss($response);
 
-            // Assume the URL /your/resource sets caching headers. If we retrieve
-            // it again, we should have a cache hit (response delivered by Varnish):
+            // Assume the URL /your/resource sets caching headers. If we
+            // retrieve it again, we should have a cache hit (response delivered
+            // by the caching proxy):
             $response = $this->getResponse('/your/resource');
             $this->assertHit($response);
         }
@@ -212,26 +233,34 @@ application sets influence Varnish as you expect them to::
 This example shows how you can test whether your application purges content
 correctly::
 
-    public function testCachePurge()
+    use FOS\HttpCache\Test\CacheAssertions;
+    use FOS\HttpCache\Test\HttpCaller;
+    use FOS\HttpCache\Test\VarnishTest;
+    // or FOS\HttpCache\Test\NginxTest;
+    // or FOS\HttpCache\Test\SymfonyTest;
+
+    class YourTest extends \PHPUnit_Framework_TestCase
     {
-        // Again, Varnish is restarted, so your test is independent from
-        // other tests
+        public function testCachePurge()
+        {
+            // Again, the caching proxy is restarted, so your test is independent
+            // from other tests
 
-        $url = '/blog/articles/1';
+            $url = '/blog/articles/1';
 
-        // First request must be a cache miss
-        $this->assertMiss($this->getResponse($url));
+            // First request must be a cache miss
+            $this->assertMiss($this->getResponse($url));
 
-        // Next requests must be a hit
-        $this->assertHit($this->getResponse($url));
+            // Next requests must be a hit
+            $this->assertHit($this->getResponse($url));
 
-        // Purge
-        $this->varnish->purge('/blog/articles/1');
+            // Purge
+            $this->getProxyClient()->purge('/blog/articles/1');
 
-        // First request after must again be a miss
-        $this->assertMiss($this->getResponse($url));
+            // First request after must again be a miss
+            $this->assertMiss($this->getResponse($url));
+        }
     }
 
-Tests for Nginx look the same but extend the NginxTestCase.
 For more ideas, see this library’s functional tests in the
 :source:`tests/Functional/` directory.