documentation/manual/en/module_specs/Zend_Test-PHPUnit-Bootstrapping.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.test.phpunit.bootstrapping">
   4     <title>Bootstrapping your TestCase</title>
   5
   6     <para>
   7         As noted in the <link linkend="zend.test.phpunit.loginexample">Login
   8             example</link>, all <acronym>MVC</acronym> test cases should extend
   9         <classname>Zend_Test_PHPUnit_ControllerTestCase</classname>. This class in turn
  10         extends <classname>PHPUnit_Framework_TestCase</classname>, and gives you all the
  11         structure and assertions you'd expect from PHPUnit -- as well as some
  12         scaffolding and assertions specific to Zend Framework's <acronym>MVC</acronym>
  13         implementation.
  14     </para>
  15
  16     <para>
  17         In order to test your <acronym>MVC</acronym> application, you will need to bootstrap it.
  18         There are several ways to do this, all of which hinge on the public
  19         <varname>$bootstrap</varname> property.
  20     </para>
  21
  22     <para>
  23         First, and probably most straight-forward, simply create a
  24         <classname>Zend_Application</classname> instance as you would in your
  25         <filename>index.php</filename>, and assign it to the <varname>$bootstrap</varname> property.
  26         Typically, you will do this in your <methodname>setUp()</methodname> method; you will need
  27         to call <methodname>parent::setUp()</methodname> when done:
  28     </para>
  29
  30     <programlisting language="php"><![CDATA[
  31 class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
  32 {
  33     public function setUp()
  34     {
  35         // Assign and instantiate in one step:
  36         $this->bootstrap = new Zend_Application(
  37             'testing',
  38             APPLICATION_PATH . '/configs/application.ini'
  39         );
  40         parent::setUp();
  41     }
  42 }
  43 ]]></programlisting>
  44
  45     <para>
  46         Second, you can set this property to point to a file. If you do
  47         this, the file should <emphasis>not</emphasis> dispatch the front
  48         controller, but merely setup the front controller and any application
  49         specific needs.
  50     </para>
  51
  52     <programlisting language="php"><![CDATA[
  53 class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
  54 {
  55     public $bootstrap = '/path/to/bootstrap/file.php'
  56
  57     // ...
  58 }
  59 ]]></programlisting>
  60
  61     <para>
  62         Third, you can provide a <acronym>PHP</acronym> callback to execute in order to bootstrap
  63         your application. This method is seen in the <link
  64             linkend="zend.test.phpunit.loginexample">Login example</link>. If
  65         the callback is a function or static method, this could be set at the
  66         class level:
  67     </para>
  68
  69     <programlisting language="php"><![CDATA[
  70 class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
  71 {
  72     public $bootstrap = array('App', 'bootstrap');
  73
  74     // ...
  75 }
  76 ]]></programlisting>
  77
  78     <para>
  79         In cases where an object instance is necessary, we recommend performing
  80         this in your <methodname>setUp()</methodname> method:
  81     </para>
  82
  83     <programlisting language="php"><![CDATA[
  84 class UserControllerTest extends Zend_Test_PHPUnit_ControllerTestCase
  85 {
  86     public function setUp()
  87     {
  88         // Use the 'start' method of a Bootstrap object instance:
  89         $bootstrap = new Bootstrap('test');
  90         $this->bootstrap = array($bootstrap, 'start');
  91         parent::setUp();
  92     }
  93 }
  94 ]]></programlisting>
  95
  96     <para>
  97         Note the call to <methodname>parent::setUp()</methodname>; this is necessary, as
  98         the <methodname>setUp()</methodname> method of
  99         <classname>Zend_Test_PHPUnit_ControllerTestCase</classname> will perform the
 100         remainder of the bootstrapping process (which includes calling the
 101         callback).
 102     </para>
 103
 104     <para>
 105         During normal operation, the <methodname>setUp()</methodname> method will bootstrap
 106         the application. This process first will include cleaning up the
 107         environment to a clean request state, resetting any plugins and
 108         helpers, resetting the front controller instance, and creating new
 109         request and response objects. Once this is done, it will then either
 110         <methodname>include()</methodname> the file specified in <varname>$bootstrap</varname>, or
 111         call the callback specified.
 112     </para>
 113
 114     <para>
 115         Bootstrapping should be as close as possible to how the application
 116         will be bootstrapped. However, there are several caveats:
 117     </para>
 118
 119     <itemizedlist>
 120         <listitem>
 121             <para>
 122                 Do not provide alternate implementations of the Request and
 123                 Response objects; they will not be used.
 124                 <classname>Zend_Test_PHPUnit_ControllerTestCase</classname> uses custom
 125                 request and response objects,
 126                 <classname>Zend_Controller_Request_HttpTestCase</classname> and
 127                 <classname>Zend_Controller_Response_HttpTestCase</classname>, respectively.
 128                 These objects provide methods for setting up the request
 129                 environment in targeted ways, and pulling response artifacts in
 130                 specific ways.
 131             </para>
 132         </listitem>
 133
 134         <listitem>
 135             <para>
 136                 Do not expect to test server specifics. In other words, the tests
 137                 are not a guarantee that the code will run on a specific server
 138                 configuration, but merely that the application should run as
 139                 expected should the router be able to route the given request. To
 140                 this end, do not set server-specific headers in the request object.
 141             </para>
 142         </listitem>
 143     </itemizedlist>
 144
 145     <para>
 146         Once the application is bootstrapped, you can then start creating
 147         your tests.
 148     </para>
 149 </sect2>
 150 <!--
 151 vim:se ts=4 sw=4 et:
 152 -->