Skip to content

Commit 8180937

Browse files
hpatoiodbu
hpatoio
authored and
dbu
committed
Add nginx to testing documentation and cleanup testing configuration information.
1 parent 34b1600 commit 8180937

File tree

3 files changed

+118
-80
lines changed

3 files changed

+118
-80
lines changed

‎doc/testing-your-application.rst

Lines changed: 65 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -3,42 +3,25 @@
33
Testing Your Application
44
========================
55

6-
This chapter describes how to test your application against a Varnish instance.
6+
This chapter describes how to test your application against you reverse proxy
7+
instance.
78

8-
VarnishTestCase
9-
---------------
9+
The FOSHttpCache library provides base test case classes to help you write
10+
functional tests. This may be helpful to test the way your application sets
11+
caching headers and invalidates cached content.
1012

11-
The FOSHttpCache library provides a base test case to help you write functional
12-
tests against a Varnish instance. This may be helpful to test the way your
13-
application sets caching headers and invalidates cached content.
13+
By having your test classes extend one of the testCase classes, you get:
1414

15-
By having your test classes extend ``VarnishTestCase``, you get:
16-
17-
* independent tests: all previously cached content is removed by restarting
18-
Varnish in the test setUp method
19-
* ``$this->varnish`` referring to an instance of this library’s Varnish client
20-
that is configured to talk to your Varnish server
15+
* independent tests: all previously cached content is removed in the tests
16+
``setUp`` method. The way this is done depends on which reverse proxy you use;
17+
* an instance of this library’s client that is configured to talk to your
18+
reverse proxy server. See reverse proxy specific sections for details;
2119
* convenience methods for executing HTTP requests to your application:
22-
``$this->getHttpClient()`` and ``$this->getResponse()``
20+
``$this->getHttpClient()`` and ``$this->getResponse()``;
2321
* custom assertions ``assertHit`` and ``assertMiss`` for validating a cache hit/miss.
2422

25-
Configuration
26-
-------------
27-
28-
By default, the ``VarnishTestCase`` starts and stops a Varnish server for you.
29-
All you have to do, is to refer the class to your Varnish configuration (VCL)
30-
file. The recommended way to configure the test case is by setting constants
31-
in your `phpunit.xml`. Alternatively, you can override the getter methods:
32-
33-
======================= ========================= ============ ==========================================
34-
Constant Getter Default Description
35-
======================= ========================= ============ ==========================================
36-
``VARNISH_FILE`` ``getConfigFile()`` your Varnish configuration (VCL) file
37-
``VARNISH_BINARY`` ``getBinary()`` ``varnishd`` your Varnish binary
38-
``VARNISH_PORT`` ``getCachingProxyPort()`` ``6181`` port Varnish listens on
39-
``VARNISH_MGMT_PORT`` ``getVarnishMgmtPort()`` ``6182`` Varnish management port
40-
``WEB_SERVER_HOSTNAME`` ``getHostName()`` hostname your application can be reached at
41-
======================= ========================= ============ ==========================================
23+
The recommended way to configure the test case is by setting constants
24+
in your `phpunit.xml`. Alternatively, you can override the getter methods.
4225

4326
Setting Constants
4427
~~~~~~~~~~~~~~~~~
@@ -67,13 +50,63 @@ You can override getters in your test class in the following way::
6750
}
6851
}
6952

53+
VarnishTestCase
54+
---------------
55+
56+
Configuration
57+
'''''''''''''
58+
59+
By default, the ``VarnishTestCase`` starts and stops a Varnish server for you.
60+
All you have to do is to set your Varnish configuration (VCL) file.
61+
62+
======================= ========================= ================================================== ============================================
63+
Constant Getter Default Description
64+
======================= ========================= ================================================== ============================================
65+
``VARNISH_FILE`` ``getConfigFile()`` your Varnish configuration (VCL) file
66+
``VARNISH_BINARY`` ``getBinary()`` ``varnishd`` your Varnish binary
67+
``VARNISH_PORT`` ``getCachingProxyPort()`` ``6181`` port Varnish listens on
68+
``VARNISH_MGMT_PORT`` ``getVarnishMgmtPort()`` ``6182`` Varnish management port
69+
``VARNISH_CACHE_DIR`` ``getCacheDir()`` ``sys_get_temp_dir()`` + ``/foshttpcache-varnish`` directory to use for cache
70+
``VARNISH_VERSION`` ``getVarnishVersion()`` ``3`` installed varnish application version
71+
``WEB_SERVER_HOSTNAME`` ``getHostName()`` hostname your application can be reached at
72+
======================= ========================= ================================================== ============================================
73+
7074
Enable Assertions
71-
~~~~~~~~~~~~~~~~~
75+
'''''''''''''''''
7276

7377
For the `assertHit` and `assertMiss` assertions to work, you should add a
7478
:ref:`custom X-Debug header <varnish_debugging>` to responses served
7579
by your Varnish.
7680

81+
NginxTestCase
82+
-------------
83+
84+
Configuration
85+
'''''''''''''
86+
87+
By default, the ``NginxTestCase`` starts and stops NGINX server for you and deletes
88+
all cached contents. You have to set your NGINX configuration file.
89+
90+
These are all the configurations you can change
91+
92+
======================= ========================= ================================================ ==========================================
93+
Constant Getter Default Description
94+
======================= ========================= ================================================ ==========================================
95+
``NGINX_FILE`` ``getConfigFile()`` your NGINX configuration file
96+
``NGINX_BINARY`` ``getBinary()`` ``nginx`` your NGINX binary
97+
``NGINX_PORT`` ``getCachingProxyPort()`` ``8088`` port NGINX listens on
98+
``NGINX_CACHE_PATH`` ``getCacheDir()`` ``sys_get_temp_dir()`` + ``/foshttpcache-nginx`` directory to use for cache
99+
Must match `proxy_cache_path` directive in
100+
your configuration file.
101+
``WEB_SERVER_HOSTNAME`` ``getHostName()`` hostname your application can be reached at
102+
======================= ========================= ================================================ ==========================================
103+
104+
Enable Assertions
105+
'''''''''''''''''
106+
107+
For the `assertHit` and `assertMiss` assertions to work, you should add the HTTP
108+
header ``X-Cache`` to your responses
109+
77110
Usage
78111
-----
79112

@@ -127,7 +160,6 @@ correctly::
127160
$this->assertMiss($this->getResponse($url));
128161
}
129162

130-
163+
Tests for Nginx look the same but extend the NginxTestCase.
131164
For more ideas, see this library’s functional tests in the
132165
:source:`tests/Functional/` directory.
133-

‎src/Test/NginxTestCase.php

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,32 +17,38 @@
1717
/**
1818
* A phpunit base class to write functional tests with NGINX.
1919
*
20-
* You can define a couple of constants in your phpunit to control how this
21-
* test behaves.
20+
* You can define constants in your phpunit.xml to control how this test behaves.
21+
*
22+
* Note that the WEB_SERVER_HOSTNAME must also match with what you have in your
23+
* NGINX configuration file.
2224
*
2325
* To define constants in the phpunit file, use this syntax:
2426
* <php>
2527
* <const name="NGINX_FILE" value="./tests/FOS/HttpCache/Tests/Functional/Fixtures/nginx/fos.conf" />
2628
* </php>
2729
*
28-
* NGINX_BINARY Executable for NGINX. This can also be the full path
29-
* to the file if the binary is not automatically found
30-
* (default nginx)
31-
* NGINX_PORT Test NGINX port to use (default 8088)
32-
* NGINX_FILE NGINX configuration file (required if not passed to setUp)
33-
* NGINX_CACHE_PATH NGINX configuration file (required if not passed to setUp)
30+
* NGINX_FILE NGINX configuration file (required if not passed to setUp)
31+
* NGINX_BINARY Executable for NGINX. This can also be the full path
32+
* to the file if the binary is not automatically found
33+
* (default nginx)
34+
* NGINX_PORT Port NGINX listens to (default 8088)
35+
* NGINX_CACHE_PATH directory to use for cache
36+
* Must match `proxy_cache_path` directive in
37+
* your configuration file.
38+
* (default sys_get_temp_dir() + '/foshttpcache-nginx')
39+
* WEB_SERVER_HOSTNAME hostname where your application can be reached (required)
3440
*/
3541
abstract class NginxTestCase extends ProxyTestCase
3642
{
3743
/**
38-
* @var NginxProxy
44+
* @var Nginx
3945
*/
40-
protected $proxy;
46+
protected $proxyClient;
4147

4248
/**
43-
* @var Nginx
49+
* @var NginxProxy
4450
*/
45-
protected $proxyClient;
51+
protected $proxy;
4652

4753
/**
4854
* The default implementation looks at the constant NGINX_FILE.

‎src/Test/VarnishTestCase.php

Lines changed: 35 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,7 @@
1717
/**
1818
* A phpunit base class to write functional tests with varnish.
1919
*
20-
* You can define a couple of constants in your phpunit to control how this
21-
* test behaves.
20+
* You can define constants in your phpunit to control how this test behaves.
2221
*
2322
* Note that the WEB_SERVER_HOSTNAME must also match with what you have in your
2423
* .vcl file.
@@ -28,15 +27,16 @@
2827
* <const name="VARNISH_FILE" value="./tests/Functional/Fixtures/varnish-3/fos.vcl" />
2928
* </php>
3029
*
31-
* VARNISH_BINARY executable for varnish. this can also be the full path
30+
* VARNISH_FILE Varnish configuration file (required if not passed to setUp)
31+
* VARNISH_BINARY executable for Varnish. this can also be the full path
3232
* to the file if the binary is not automatically found
3333
* (default varnishd)
34-
* VARNISH_PORT test varnish port to use (default 6181)
35-
* VARNISH_MGMT_PORT test varnish mgmt port (default 6182)
36-
* VARNISH_FILE varnish configuration file (required if not passed to setUp)
34+
* VARNISH_PORT port Varnish listens on (default 6181)
35+
* VARNISH_MGMT_PORT Varnish management port (default 6182)
3736
* VARNISH_CACHE_DIR directory to use for cache
38-
* (default /tmp/foshttpcache-test)
39-
* WEB_SERVER_HOSTNAME name of the webserver varnish has to talk to (required)
37+
* (default sys_get_temp_dir() + '/foshttpcache-varnish')
38+
* VARNISH_VERSION Version of varnish: 3 or 4, defaults to 3.
39+
* WEB_SERVER_HOSTNAME hostname/IP your application can be reached at (required)
4040
*/
4141
abstract class VarnishTestCase extends ProxyTestCase
4242
{
@@ -50,33 +50,6 @@ abstract class VarnishTestCase extends ProxyTestCase
5050
*/
5151
protected $proxy;
5252

53-
/**
54-
* {@inheritdoc}
55-
*/
56-
protected function getProxy()
57-
{
58-
if (null === $this->proxy) {
59-
$this->proxy = new VarnishProxy($this->getConfigFile());
60-
if ($this->getBinary()) {
61-
$this->proxy->setBinary($this->getBinary());
62-
}
63-
64-
if ($this->getCachingProxyPort()) {
65-
$this->proxy->setPort($this->getCachingProxyPort());
66-
}
67-
68-
if ($this->getVarnishMgmtPort()) {
69-
$this->proxy->setManagementPort($this->getVarnishMgmtPort());
70-
}
71-
72-
if ($this->getCacheDir()) {
73-
$this->proxy->setCacheDir($this->getCacheDir());
74-
}
75-
}
76-
77-
return $this->proxy;
78-
}
79-
8053
/**
8154
* The default implementation looks at the constant VARNISH_FILE.
8255
*
@@ -143,6 +116,33 @@ protected function getVarnishVersion()
143116
return getenv('VARNISH_VERSION') ?: 3;
144117
}
145118

119+
/**
120+
* {@inheritdoc}
121+
*/
122+
protected function getProxy()
123+
{
124+
if (null === $this->proxy) {
125+
$this->proxy = new VarnishProxy($this->getConfigFile());
126+
if ($this->getBinary()) {
127+
$this->proxy->setBinary($this->getBinary());
128+
}
129+
130+
if ($this->getCachingProxyPort()) {
131+
$this->proxy->setPort($this->getCachingProxyPort());
132+
}
133+
134+
if ($this->getVarnishMgmtPort()) {
135+
$this->proxy->setManagementPort($this->getVarnishMgmtPort());
136+
}
137+
138+
if ($this->getCacheDir()) {
139+
$this->proxy->setCacheDir($this->getCacheDir());
140+
}
141+
}
142+
143+
return $this->proxy;
144+
}
145+
146146
/**
147147
* Get Varnish proxy client
148148
*

0 commit comments

Comments
 (0)