[Sommaire] [Imprimer]

   1  <html>
   2  <head>
   3  <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
   4  <title>SimpleTest for PHP group test documentation</title>
   5  <link rel="stylesheet" type="text/css" href="docs.css" title="Styles">
   6  </head>
   7  <body>
   8  <div class="menu_back">
   9  <div class="menu">
  10  <h2>
  11  <a href="index.html">SimpleTest</a>
  12  </h2>
  13  <ul>
  14  <li>
  15  <a href="overview.html">Overview</a>
  16  </li>
  17  <li>
  18  <a href="unit_test_documentation.html">Unit tester</a>
  19  </li>
  20  <li>
  21  <span class="chosen">Group tests</span>
  22  </li>
  23  <li>
  24  <a href="mock_objects_documentation.html">Mock objects</a>
  25  </li>
  26  <li>
  27  <a href="partial_mocks_documentation.html">Partial mocks</a>
  28  </li>
  29  <li>
  30  <a href="reporter_documentation.html">Reporting</a>
  31  </li>
  32  <li>
  33  <a href="expectation_documentation.html">Expectations</a>
  34  </li>
  35  <li>
  36  <a href="web_tester_documentation.html">Web tester</a>
  37  </li>
  38  <li>
  39  <a href="form_testing_documentation.html">Testing forms</a>
  40  </li>
  41  <li>
  42  <a href="authentication_documentation.html">Authentication</a>
  43  </li>
  44  <li>
  45  <a href="browser_documentation.html">Scriptable browser</a>
  46  </li>
  47  </ul>
  48  </div>
  49  </div>
  50  <h1>Group Test documentation</h1>
  51  <div class="content">
  52          <p>
  53  <a class="target" name="group">
  54  <h2>Grouping tests</h2>
  55  </a>
  56  </p>
  57              <p>
  58                  To run test cases as part of a group the test cases should really
  59                  be placed in files without the runner code...
  60  <pre>
  61  <strong>&lt;?php
  62      require_once('../classes/io.php');
  63  
  64      class FileTester extends UnitTestCase {
  65          ...
  66      }
  67  
  68      class SocketTester extends UnitTestCase {
  69          ...
  70      }
  71  ?&gt;</strong>
  72  </pre>
  73                  As many cases as needed can appear in a single file.
  74                  They should include any code they need, such as the library
  75                  being tested, but none of the simple test libraries.
  76              </p>
  77              <p>
  78                  If you have extended any test cases, you can include them
  79                  as well.
  80  <pre>
  81  &lt;?php
  82      require_once('../classes/io.php');
  83  <strong>
  84      class MyFileTestCase extends UnitTestCase {
  85          ...
  86      }
  87      SimpleTest::ignore('MyFileTestCase');</strong>
  88  
  89      class FileTester extends MyFileTestCase {
  90          ...
  91      }
  92  
  93      class SocketTester extends UnitTestCase {
  94          ...
  95      }
  96  ?&gt;
  97  </pre>
  98                  The <span class="new_code">FileTester</span> class does
  99                  not contain any actual tests, but is a base class for other
 100                  test cases.
 101                  For this reason we use the
 102                  <span class="new_code">SimpleTestOptions::ignore()</span> directive
 103                  to tell the upcoming group test to ignore it.
 104                  This directive can appear anywhere in the file and works
 105                  when a whole file of test cases is loaded (see below).
 106                  We will call this sample <em>file_test.php</em>.
 107              </p>
 108              <p>
 109                  Next we create a group test file, called say <em>group_test.php</em>.
 110                  You will think of a better name I am sure.
 111                  We will add the test file using a safe method...
 112  <pre>
 113  &lt;?php
 114      require_once('simpletest/unit_tester.php');
 115      require_once('simpletest/reporter.php');<strong>
 116      require_once('file_test.php');
 117  
 118      $test = &amp;new GroupTest('All file tests');
 119      $test-&gt;addTestCase(new FileTestCase());
 120      $test-&gt;run(new HtmlReporter());</strong>
 121  ?&gt;
 122  </pre>
 123                  This instantiates the test case before the test suite is
 124                  run.
 125                  This could get a little expensive with a large number of test
 126                  cases, so another method is provided that will only
 127                  instantiate the class when it is needed...
 128  <pre>
 129  &lt;?php
 130      require_once('simpletest/unit_tester.php');
 131      require_once('simpletest/reporter.php');
 132      require_once('file_test.php');
 133  
 134      $test = &amp;new GroupTest('All file tests');<strong>
 135      $test-&gt;addTestClass('FileTestCase');</strong>
 136      $test-&gt;run(new HtmlReporter());
 137  ?&gt;
 138  </pre>
 139                  The problem with this method is that for every test case
 140                  that we add we will have
 141                  to <span class="new_code">require_once()</span> the test code
 142                  file and manually instantiate each and every test case.
 143                  We can save a lot of typing with...
 144  <pre>
 145  &lt;?php
 146      require_once('simpletest/unit_tester.php');
 147      require_once('simpletest/reporter.php');
 148  
 149      $test = &amp;new GroupTest('All file tests');<strong>
 150      $test-&gt;addTestFile('file_test.php');</strong>
 151      $test-&gt;run(new HtmlReporter());
 152  ?&amp;gt;
 153  </pre>
 154                  What happens here is that the <span class="new_code">GroupTest</span>
 155                  class has done the <span class="new_code">require_once()</span>
 156                  for us.
 157                  It then checks to see if any new test case classes
 158                  have been created by the new file and automatically adds
 159                  them to the group test.
 160                  Now all we have to do is add each new file.
 161              </p>
 162              <p>
 163                  There are two things that could go wrong and which require care...
 164                  <ol>
 165                      <li>
 166                          The file could already have been parsed by PHP and so no
 167                          new classes will have been added. You should make
 168                          sure that the test cases are only included in this file
 169                          and no others.
 170                      </li>
 171                      <li>
 172                          New test case extension classes that get included will be
 173                          placed in the group test and run also.
 174                          You will need to add a <span class="new_code">SimpleTestOptions::ignore()</span>
 175                          directive for these classes or make sure that they are included
 176                          before the <span class="new_code">GroupTest::addTestFile()</span>
 177                          line.
 178                      </li>
 179                  </ol>
 180              </p>
 181          
 182          <p>
 183  <a class="target" name="higher">
 184  <h2>Higher groupings</h2>
 185  </a>
 186  </p>
 187              <p>
 188                  The above method places all of the test cases into one large group.
 189                  For larger projects though this may not be flexible enough; you
 190                  may want to group the tests in all sorts of ways.
 191              </p>
 192              <p>
 193                  To get a more flexible group test we can subclass
 194                  <span class="new_code">GroupTest</span> and then instantiate it as needed...
 195  <pre>
 196  &lt;?php
 197      require_once('simpletest/unit_tester.php');
 198      require_once('simpletest/reporter.php');
 199      <strong>
 200      class FileGroupTest extends GroupTest {
 201          function FileGroupTest() {
 202              $this-&gt;GroupTest('All file tests');
 203              $this-&gt;addTestFile('file_test.php');
 204          }
 205      }</strong>
 206  ?&gt;
 207  </pre>
 208                  This effectively names the test in the constructor and then
 209                  adds our test cases and a single group below.
 210                  Of course we can add more than one group at this point.
 211                  We can now invoke the tests from a separate runner file...
 212  <pre>
 213  &lt;?php
 214      require_once('file_group_test.php');
 215      <strong>
 216      $test = &amp;new FileGroupTest();
 217      $test-&gt;run(new HtmlReporter());</strong>
 218  ?&gt;
 219  </pre>
 220                  ...or we can group them into even larger group tests...
 221  <pre>
 222  &lt;?php
 223      require_once('file_group_test.php');
 224      <strong>
 225      $test = &amp;new BigGroupTest('Big group');
 226      $test-&gt;addTestCase(new FileGroupTest());
 227      $test-&gt;addTestCase(...);
 228      $test-&gt;run(new HtmlReporter());</strong>
 229  ?&gt;
 230  </pre>
 231                  If we still wish to run the original group test and we
 232                  don't want all of these little runner files, we can
 233                  put the test runner code around guard bars when we create
 234                  each group.
 235  <pre>
 236  &lt;?php
 237      class FileGroupTest extends GroupTest {
 238          function FileGroupTest() {
 239              $this-&gt;GroupTest('All file tests');
 240              $test-&gt;addTestFile('file_test.php');
 241          }
 242      }
 243      <strong>
 244      if (! defined('RUNNER')) {
 245          define('RUNNER', true);</strong>
 246          $test = &amp;new FileGroupTest();
 247          $test-&gt;run(new HtmlReporter());
 248      }
 249  ?&gt;
 250  </pre>
 251                  This approach requires the guard to be set when including
 252                  the group test file, but this is still less hassle than
 253                  lots of separate runner files.
 254                  You include the same guard on the top level tests to make sure
 255                  that <span class="new_code">run()</span> will run once only
 256                  from the top level script that has been invoked.
 257  <pre>
 258  &lt;?php<strong>
 259      define('RUNNER', true);</strong>
 260      require_once('file_group_test.php');
 261  
 262      $test = &amp;new BigGroupTest('Big group');
 263      $test-&gt;addTestCase(new FileGroupTest());
 264      $test-&gt;addTestCase(...);
 265      $test-&gt;run(new HtmlReporter());
 266  ?&gt;
 267  </pre>
 268                  As with the normal test cases, a <span class="new_code">GroupTest</span> can
 269                  be loaded with the <span class="new_code">GroupTest::addTestFile()</span> method.
 270  <pre>
 271  &lt;?php
 272      define('RUNNER', true);
 273  
 274      $test = &amp;new BigGroupTest('Big group');<strong>
 275      $test-&gt;addTestFile('file_group_test.php');
 276      $test-&gt;addTestFile(...);</strong>
 277      $test-&gt;run(new HtmlReporter());
 278  ?&gt;
 279  </pre>
 280              </p>
 281          
 282          <p>
 283  <a class="target" name="legacy">
 284  <h2>Integrating legacy test cases</h2>
 285  </a>
 286  </p>
 287              <p>
 288                  If you already have unit tests for your code or are extending external
 289                  classes that have tests, it is unlikely that all of the test cases
 290                  are in SimpleTest format.
 291                  Fortunately it is possible to incorporate test cases from other
 292                  unit testers directly into SimpleTest group tests.
 293              </p>
 294              <p>
 295                  Say we have the following
 296                  <a href="http://sourceforge.net/projects/phpunit">PhpUnit</a>
 297                  test case in the file <em>config_test.php</em>...
 298  <pre>
 299  <strong>class ConfigFileTest extends TestCase {
 300      function ConfigFileTest() {
 301          $this-&gt;TestCase('Config file test');
 302      }
 303      
 304      function testContents() {
 305          $config = new ConfigFile('test.conf');
 306          $this-&gt;assertRegexp('/me/', $config-&gt;getValue('username'));
 307      }
 308  }</strong>
 309  </pre>
 310                  The group test can recognise this as long as we include
 311                  the appropriate adapter class before we add the test
 312                  file...
 313  <pre>
 314  &lt;?php
 315      require_once('simpletest/unit_tester.php');
 316      require_once('simpletest/reporter.php');<strong>
 317      require_once('simpletest/adapters/phpunit_test_case.php');</strong>
 318  
 319      $test = &amp;new GroupTest('All file tests');<strong>
 320      $test-&gt;addTestFile('config_test.php');</strong>
 321      $test-&gt;run(new HtmlReporter());
 322  ?&gt;
 323  </pre>
 324                  There are only two adapters, the other is for the
 325                  <a href="http://pear.php.net/manual/en/package.php.phpunit.php">PEAR</a>
 326                  1.0 unit tester...
 327  <pre>
 328  &lt;?php
 329      require_once('simpletest/unit_tester.php');
 330      require_once('simpletest/reporter.php');<strong>
 331      require_once('simpletest/adapters/pear_test_case.php');</strong>
 332  
 333      $test = &amp;new GroupTest('All file tests');<strong>
 334      $test-&gt;addTestFile('some_pear_test_cases.php');</strong>
 335      $test-&gt;run(new HtmlReporter());
 336  ?&gt;
 337  </pre>
 338                  The PEAR test cases can be freely mixed with SimpleTest
 339                  ones even in the same test file,
 340                  but you cannot use SimpleTest assertions in the legacy
 341                  test case versions.
 342                  This is done as a check that you are not accidently making
 343                  your test cases completely dependent on SimpleTest.
 344                  You may want to do a PEAR release of your library for example
 345                  which would mean shipping it with valid PEAR::PhpUnit test
 346                  cases.
 347              </p>
 348          
 349      </div>
 350  <div class="copyright">
 351              Copyright<br>Marcus Baker, Jason Sweat, Perrick Penet 2004
 352          </div>
 353  </body>
 354  </html>