Skip to content

Commit

Permalink
Merge pull request #205 from FriendsOfSymfony/document-symfony-test-case
Browse files Browse the repository at this point in the history 
Document symfony test case
  • Loading branch information
@ddeboer
ddeboer committed Jun 2, 2015
2 parents 1741f68 + 1e3138c commit 54117e2
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 17 deletions.
2 changes: 2 additions & 0 deletions doc/cache-invalidator.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
86 changes: 72 additions & 14 deletions doc/testing-your-application.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -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
'''''''''''''''''
Expand All @@ -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
Expand All @@ -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
'''''''''''''''''
Expand All @@ -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
-----

Expand Down
7 changes: 4 additions & 3 deletions src/Test/SymfonyTestCase.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down

0 comments on commit 54117e2

Please sign in to comment.