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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.test.phpunit.assertions">
   4     <title>Assertions</title>
   5
   6     <para>
   7         Assertions are at the heart of Unit Testing; you use them to verify
   8         that the results are what you expect. To this end,
   9         <classname>Zend_Test_PHPUnit_ControllerTestCase</classname> provides a number of
  10         assertions to make testing your <acronym>MVC</acronym> apps and controllers simpler.
  11     </para>
  12
  13     <sect3 id="zend.test.phpunit.assertions.query">
  14         <title>CSS Selector Assertions</title>
  15
  16         <para>
  17             <acronym>CSS</acronym> selectors are an easy way to verify that certain artifacts are
  18             present in the response content. They also make it trivial to
  19             ensure that items necessary for Javascript UIs and/or <acronym>AJAX</acronym>
  20             integration will be present; most JS toolkits provide some
  21             mechanism for pulling DOM elements based on <acronym>CSS</acronym> selectors, so the
  22             syntax would be the same.
  23         </para>
  24
  25         <para>
  26             This functionality is provided via <link
  27                 linkend="zend.dom.query">Zend_Dom_Query</link>, and integrated
  28             into a set of 'Query' assertions. Each of these assertions takes
  29             as their first argument a <acronym>CSS</acronym> selector, with optionally additional
  30             arguments and/or an error message, based on the assertion type. You
  31             can find the rules for writing the <acronym>CSS</acronym> selectors in the <link
  32                 linkend="zend.dom.query.operation">Zend_Dom_Query theory of
  33                 operation chapter</link>. Query assertions include:
  34         </para>
  35
  36         <itemizedlist>
  37             <listitem>
  38                 <para>
  39                     <methodname>assertQuery($path, $message = '')</methodname>: assert that
  40                     one or more DOM elements matching the given <acronym>CSS</acronym> selector are
  41                     present. If a <varname>$message</varname> is present, it will be
  42                     prepended to any failed assertion message.
  43                 </para>
  44             </listitem>
  45
  46             <listitem>
  47                 <para>
  48                     <code>assertQueryContentContains($path, $match, $message =
  49                         '')</code>: assert that one or more DOM elements matching
  50                     the given <acronym>CSS</acronym> selector are present, and that at least one
  51                     contains the content provided in <varname>$match</varname>. If a
  52                     <varname>$message</varname> is present, it will be prepended to any
  53                     failed assertion message.
  54                 </para>
  55             </listitem>
  56
  57             <listitem>
  58                 <para>
  59                     <code>assertQueryContentRegex($path, $pattern, $message =
  60                         '')</code>: assert that one or more DOM elements matching
  61                     the given <acronym>CSS</acronym> selector are present, and that at least one
  62                     matches the regular expression provided in
  63                     <varname>$pattern</varname>. If a <varname>$message</varname> is present,
  64                     it will be prepended to any failed assertion message.
  65                 </para>
  66             </listitem>
  67
  68             <listitem>
  69                 <para>
  70                     <code>assertQueryCount($path, $count, $message =
  71                         '')</code>: assert that there are exactly
  72                     <varname>$count</varname> DOM elements matching the given <acronym>CSS</acronym>
  73                     selector present. If a <varname>$message</varname> is present, it
  74                     will be prepended to any failed assertion message.
  75                 </para>
  76             </listitem>
  77
  78             <listitem>
  79                 <para>
  80                     <code>assertQueryCountMin($path, $count, $message =
  81                         '')</code>: assert that there are at least
  82                     <varname>$count</varname> DOM elements matching the given <acronym>CSS</acronym>
  83                     selector present. If a <varname>$message</varname> is present, it
  84                     will be prepended to any failed assertion message.
  85                     <emphasis>Note:</emphasis> specifying a value of 1 for
  86                     <varname>$count</varname> is the same as simply using
  87                     <methodname>assertQuery()</methodname>.
  88                 </para>
  89             </listitem>
  90
  91             <listitem>
  92                 <para>
  93                     <code>assertQueryCountMax($path, $count, $message =
  94                         '')</code>: assert that there are no more than
  95                     <varname>$count</varname> DOM elements matching the given <acronym>CSS</acronym>
  96                     selector present. If a <varname>$message</varname> is present, it
  97                     will be prepended to any failed assertion message.
  98                     <emphasis>Note:</emphasis> specifying a value of 1 for
  99                     <varname>$count</varname> is the same as simply using
 100                     <methodname>assertQuery()</methodname>.
 101                 </para>
 102             </listitem>
 103         </itemizedlist>
 104
 105         <para>
 106             Additionally, each of the above has a 'Not' variant that provides a
 107             negative assertion: <methodname>assertNotQuery()</methodname>,
 108             <methodname>assertNotQueryContentContains()</methodname>,
 109             <methodname>assertNotQueryContentRegex()</methodname>, and
 110             <methodname>assertNotQueryCount()</methodname>. (Note that the min and
 111             max counts do not have these variants, for what should be obvious
 112             reasons.)
 113         </para>
 114     </sect3>
 115
 116     <sect3 id="zend.test.phpunit.assertions.xpath">
 117         <title>XPath Assertions</title>
 118
 119         <para>
 120             Some developers are more familiar with XPath than with <acronym>CSS</acronym>
 121             selectors, and thus XPath variants of all the <link
 122                 linkend="zend.test.phpunit.assertions.query">Query
 123                 assertions</link> are also provided. These are:
 124         </para>
 125
 126         <itemizedlist>
 127             <listitem>
 128                 <para>
 129                     <methodname>assertXpath($path, $message = '')</methodname>
 130                 </para>
 131             </listitem>
 132
 133             <listitem>
 134                 <para>
 135                     <methodname>assertNotXpath($path, $message = '')</methodname>
 136                 </para>
 137             </listitem>
 138
 139             <listitem>
 140                 <para>
 141                     <methodname>assertXpathContentContains($path, $match, $message =
 142                         '')</methodname>
 143                 </para>
 144             </listitem>
 145
 146             <listitem>
 147                 <para>
 148                     <methodname>assertNotXpathContentContains($path, $match, $message =
 149                         '')</methodname>
 150                 </para>
 151             </listitem>
 152
 153             <listitem>
 154                 <para>
 155                     <methodname>assertXpathContentRegex($path, $pattern, $message = '')</methodname>
 156                 </para>
 157             </listitem>
 158
 159             <listitem>
 160                 <para>
 161                     <methodname>assertNotXpathContentRegex($path, $pattern, $message =
 162                         '')</methodname>
 163                 </para>
 164             </listitem>
 165
 166             <listitem>
 167                 <para>
 168                     <methodname>assertXpathCount($path, $count, $message = '')</methodname>
 169                 </para>
 170             </listitem>
 171
 172             <listitem>
 173                 <para>
 174                     <methodname>assertNotXpathCount($path, $count, $message = '')</methodname>
 175                 </para>
 176             </listitem>
 177
 178             <listitem>
 179                 <para>
 180                     <methodname>assertXpathCountMin($path, $count, $message = '')</methodname>
 181                 </para>
 182             </listitem>
 183
 184             <listitem>
 185                 <para>
 186                     <methodname>assertNotXpathCountMax($path, $count, $message = '')</methodname>
 187                 </para>
 188             </listitem>
 189         </itemizedlist>
 190     </sect3>
 191
 192     <sect3 id="zend.test.phpunit.assertions.redirect">
 193         <title>Redirect Assertions</title>
 194
 195         <para>
 196             Often an action will redirect. Instead of following the redirect,
 197             <classname>Zend_Test_PHPUnit_ControllerTestCase</classname> allows you to
 198             test for redirects with a handful of assertions.
 199         </para>
 200
 201         <itemizedlist>
 202             <listitem>
 203                 <para>
 204                     <methodname>assertRedirect($message = '')</methodname>: assert simply that
 205                     a redirect has occurred.
 206                 </para>
 207             </listitem>
 208
 209             <listitem>
 210                 <para>
 211                     <methodname>assertNotRedirect($message = '')</methodname>: assert that no
 212                     redirect has occurred.
 213                 </para>
 214             </listitem>
 215
 216             <listitem>
 217                 <para>
 218                     <methodname>assertRedirectTo($url, $message = '')</methodname>: assert that
 219                     a redirect has occurred, and that the value of the Location
 220                     header is the <varname>$url</varname> provided.
 221                 </para>
 222             </listitem>
 223
 224             <listitem>
 225                 <para>
 226                     <methodname>assertNotRedirectTo($url, $message = '')</methodname>: assert that
 227                     a redirect has either NOT occurred, or that the value of the Location
 228                     header is NOT the <varname>$url</varname> provided.
 229                 </para>
 230             </listitem>
 231
 232             <listitem>
 233                 <para>
 234                     <methodname>assertRedirectRegex($pattern, $message = '')</methodname>:
 235                     assert that a redirect has occurred, and that the value of the
 236                     Location header matches the regular expression provided by
 237                     <varname>$pattern</varname>.
 238                 </para>
 239             </listitem>
 240
 241             <listitem>
 242                 <para>
 243                     <methodname>assertNotRedirectRegex($pattern, $message = '')</methodname>:
 244                     assert that a redirect has either NOT occurred, or that the value of the
 245                     Location header does NOT match the regular expression provided by
 246                     <varname>$pattern</varname>.
 247                 </para>
 248             </listitem>
 249         </itemizedlist>
 250     </sect3>
 251
 252     <sect3 id="zend.test.phpunit.assertions.header">
 253         <title>Response Header Assertions</title>
 254
 255         <para>
 256             In addition to checking for redirect headers, you will often need
 257             to check for specific <acronym>HTTP</acronym> response codes and headers -- for
 258             instance, to determine whether an action results in a 404 or 500
 259             response, or to ensure that <acronym>JSON</acronym> responses contain the appropriate
 260             Content-Type header. The following assertions are available.
 261         </para>
 262
 263         <itemizedlist>
 264             <listitem>
 265                 <para>
 266                     <methodname>assertResponseCode($code, $message = '')</methodname>: assert
 267                     that the response resulted in the given <acronym>HTTP</acronym> response code.
 268                 </para>
 269             </listitem>
 270
 271             <listitem>
 272                 <para>
 273                     <methodname>assertHeader($header, $message = '')</methodname>: assert
 274                     that the response contains the given header.
 275                 </para>
 276             </listitem>
 277
 278             <listitem>
 279                 <para>
 280                     <code>assertHeaderContains($header, $match, $message = '')</code>: assert that
 281                     the response contains the given header and that its content contains the given
 282                     string.
 283                 </para>
 284             </listitem>
 285
 286             <listitem>
 287                 <para>
 288                     <code>assertHeaderRegex($header, $pattern, $message = '')</code>: assert that
 289                     the response contains the given header and that its content matches the given
 290                     regex.
 291                 </para>
 292             </listitem>
 293         </itemizedlist>
 294
 295         <para>
 296             Additionally, each of the above assertions have a 'Not' variant for
 297             negative assertions.
 298         </para>
 299     </sect3>
 300
 301     <sect3 id="zend.test.phpunit.assertions.request">
 302         <title>Request Assertions</title>
 303
 304         <para>
 305             It's often useful to assert against the last run action,
 306             controller, and module; additionally, you may want to assert
 307             against the route that was matched. The following assertions can
 308             help you in this regard:
 309         </para>
 310
 311         <itemizedlist>
 312             <listitem>
 313                 <para>
 314                     <methodname>assertModule($module, $message = '')</methodname>: Assert that
 315                     the given module was used in the last dispatched action.
 316                 </para>
 317             </listitem>
 318
 319             <listitem>
 320                 <para>
 321                     <methodname>assertController($controller, $message = '')</methodname>:
 322                     Assert that the given controller was selected in the last
 323                     dispatched action.
 324                 </para>
 325             </listitem>
 326
 327             <listitem>
 328                 <para>
 329                     <methodname>assertAction($action, $message = '')</methodname>: Assert that
 330                     the given action was last dispatched.
 331                 </para>
 332             </listitem>
 333
 334             <listitem>
 335                 <para>
 336                     <methodname>assertRoute($route, $message = '')</methodname>: Assert that
 337                     the given named route was matched by the router.
 338                 </para>
 339             </listitem>
 340         </itemizedlist>
 341
 342         <para>
 343             Each also has a 'Not' variant for negative assertions.
 344         </para>
 345     </sect3>
 346 </sect2>
 347 <!--
 348 vim:se ts=4 sw=4 et:
 349 -->