[Sommaire] [Imprimer]

   1  <?php
   2  //
   3  // Definition of eZTestRunner class
   4  //
   5  // Created on: <30-Jan-2004 09:21:41 >
   6  //
   7  // SOFTWARE NAME: eZ publish
   8  // SOFTWARE RELEASE: 3.9.0
   9  // BUILD VERSION: 17785
  10  // COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
  11  // SOFTWARE LICENSE: GNU General Public License v2.0
  12  // NOTICE: >
  13  //   This program is free software; you can redistribute it and/or
  14  //   modify it under the terms of version 2.0  of the GNU General
  15  //   Public License as published by the Free Software Foundation.
  16  //
  17  //   This program is distributed in the hope that it will be useful,
  18  //   but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  //   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  //   GNU General Public License for more details.
  21  //
  22  //   You should have received a copy of version 2.0 of the GNU General
  23  //   Public License along with this program; if not, write to the Free
  24  //   Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  25  //   MA 02110-1301, USA.
  26  //
  27  //
  28  
  29  /*! \file eztestrunner.php
  30  */
  31  
  32  /*!
  33    \defgroup eZTest Testing of PHP code
  34  */
  35  
  36  /*!
  37    \class eZTestRunner eztestrunner.php
  38    \ingroup eZTest
  39    \brief eZTestRunner runs tests from test units and accumulates test results
  40  
  41    There are three uses of this class, as a client, as a test handler
  42    and as a base class for a new runner.
  43  
  44    <h3>Client usage</h3>
  45    To run test cases and test suites an instance of this class
  46    should be made and the method run() must be called with the
  47    test unit.
  48  
  49    Once the test is run you can check if all test were succesful with
  50    isSuccessful(). Detailed test information can be fetched with
  51    resultList().
  52  
  53    <h3>Test handler</h3>
  54    All tests that are run are sent an instance of an eZTestRunner
  55    class as a parameter. The test must use this instance to
  56    report failures.
  57  
  58    The tests must use the methods assert(), assertEquals(),
  59    assertNotEquals(), assertSimilar() and assertNotSimilar() for the runner
  60    to know about failed tests. It is also possible to add a custom failure
  61    with failure().
  62  
  63    Some examples:
  64    \code
  65  $tr = new eZTestRunner();
  66  
  67  function MyTests( &$tr )
  68  {
  69      $tr->assert( $a > $b );
  70      $tr->assertEquals( $c, $d );
  71      $tr->assertNotEquals( $a, $b );
  72      $tr->assertSimilar( $e, $f );
  73      $tr->assertNotSimilar( $a, $b );
  74      if ( $a - $b > $d )
  75          $tr->failure( "\$a minus \$b is not larger than \$d" );
  76  }
  77  
  78  
  79    \endcode
  80  
  81    <h3>Base class</h3>
  82    If you want to provide direct output of test results you must inherit
  83    this class and override the display() method.
  84  
  85    You can also add support for more test types by implementing the
  86    testEntryType() and runTestEntry() methods. Optionally prepareTestEntry()
  87    and finalizeTestEntry() can be implemented to add more specific
  88    preparation and finalizing code.
  89  
  90    To get output on console use eZTestCLIRunner instead.
  91  */
  92  
  93  include_once ( 'lib/ezutils/classes/ezdebug.php' );
  94  
  95  class eZTestRunner
  96  {
  97      /*!
  98       Initializes runner with no tests and successful set to \c false.
  99      */
 100      function eZTestRunner()
 101      {
 102          $this->Results = array();
 103          $this->CurrentResult = false;
 104          $this->IsSuccessful = false;
 105      }
 106  
 107      /*!
 108       Tries to run all tests defined in unit \a $unit and creates a result
 109       list and result value. Use resultList() and isSuccessful() to get the status.
 110      */
 111      function run( &$unit, $display = false, $testsToRun = true )
 112      {
 113          $this->Results = array();
 114          $this->CurrentResult = false;
 115          $this->IsSuccessful = false;
 116          if ( is_subclass_of( $unit, 'eztestunit' ) )
 117          {
 118              $this->IsSuccessful = true;
 119              $testList = $unit->testList();
 120              foreach ( $testList as $test )
 121              {
 122                  if ( is_array( $testsToRun ) and
 123                       !in_array( strtolower( $test['name'] ), $testsToRun ) )
 124                      continue;
 125                  $type = $this->testEntryType( $unit, $test );
 126                  if ( $type )
 127                  {
 128                      $test['type'] = $type;
 129                      $this->prepareTestEntry( $unit, $test );
 130  
 131                      $this->runTestEntry( $unit, $test );
 132  
 133                      $this->finalizeTestEntry( $unit, $test, $display );
 134                  }
 135                  else
 136                      $this->addToCurrentResult( false, false, $test['name'],
 137                                                 "Unknown test type for test " . $unit->name() . '::' . $test['name'] );
 138              }
 139          }
 140          else
 141          {
 142              eZDebug::writeWarning( "Tried to run test on an object which is not subclassed from eZTestUnit",
 143                                     'eZTestRunner::run' );
 144          }
 145      }
 146  
 147      /*!
 148       \virtual
 149       \protected
 150       Figures out the test type and returns a string identifiying it. The type
 151       will be set in the test entry for other functions to use for checking.
 152       \return \c false if the type could not be figure out, in which case the test is skipped.
 153      */
 154      function testEntryType( $unit, $entry )
 155      {
 156          if ( isset( $entry['method'] ) and
 157               isset( $entry['object'] ) )
 158          {
 159              return 'method';
 160          }
 161          else if ( isset( $entry['function'] ) )
 162          {
 163              return 'function';
 164          }
 165          return false;
 166      }
 167  
 168      /*!
 169       \virtual
 170       \protected
 171       Prepares the test for running, this involves setting the current test name
 172       and resetting all current test restults.
 173      */
 174      function prepareTestEntry( &$unit, $entry )
 175      {
 176          $this->setCurrentTestName( $unit->name() . '::' . $entry['name'] );
 177          $this->resetCurrentResult();
 178      }
 179  
 180      /*!
 181       \virtual
 182       \protected
 183       Finalizes the test by applying the current test results to the main
 184       result list and resetting current test name.
 185       It will also call display() if \a $display is \c true.
 186      */
 187      function finalizeTestEntry( &$unit, $entry, $display )
 188      {
 189          if ( !$this->isCurrentResultSuccessful() )
 190              $this->IsSuccessful = false;
 191  
 192          $currentResult = $this->addCurrentResult();
 193          $this->setCurrentTestName( false );
 194  
 195          if ( $display )
 196              $this->display( $currentResult );
 197      }
 198  
 199      /*!
 200       \virtual
 201       \protected
 202       Runs the actual test entry based on the \c type value.
 203  
 204       \note eZTestRunner supports \c 'method' and \c 'function' calls,
 205             to get support for more test type this method must be overriden
 206             in a subclass.
 207      */
 208      function runTestEntry( &$unit, $entry )
 209      {
 210          switch ( $entry['type'] )
 211          {
 212              case 'method':
 213              {
 214                  $object =& $entry['object'];
 215                  $method =& $entry['method'];
 216                  if ( method_exists( $object, $method ) )
 217                  {
 218                      $object->setup();
 219                      $object->$method( $this, $entry['parameter'] );
 220                      $object->teardown();
 221                  }
 222                  else
 223                  {
 224                      $this->addToCurrentResult( false, false, $entry['name'],
 225                                                 "Method $method does not exist for test object(" . get_class( $object ) . ")" );
 226                  }
 227              } break;
 228  
 229              case 'function':
 230              {
 231                  $function = $entry['function'];
 232                  if ( function_exists( $function ) )
 233                  {
 234                      $function( $this, $entry['parameter'] );
 235                  }
 236                  else
 237                  {
 238                      $this->addToCurrentResult( false, false, $entry['name'],
 239                                                 "Function $function does not exist" );
 240                  }
 241              } break;
 242          }
 243      }
 244  
 245      /*!
 246       \virtual
 247       \protected
 248       Called whenever a test is run, can be overriden to print out the test result immediately.
 249      */
 250      function display( $result )
 251      {
 252      }
 253  
 254      /*!
 255       \return \c true if the last test was successful.
 256       \note Will return \c false if no tests are run yet.
 257      */
 258      function isSuccessful()
 259      {
 260          return $this->IsSuccessful;
 261      }
 262  
 263      /*!
 264       \return an array with all the results from the last run.
 265      */
 266      function resultList()
 267      {
 268          return $this->Results;
 269      }
 270  
 271      /*!
 272       \protected
 273        Adds a failure for test \a $testName with optional message \a $message.
 274      */
 275      function addFailure( $testName, $message = false )
 276      {
 277          $messages = array();
 278          if ( $message )
 279              $messages[] = $message;
 280          $this->Results[] = array( 'status' => false,
 281                                    'assert' => false,
 282                                    'name' => $testName,
 283                                    'messages' => $messages );
 284      }
 285  
 286      /*!
 287       \protected
 288        Adds a result for test \a $testName with optional message \a $message.
 289      */
 290      function addToCurrentResult( $status, $assertName, $testName, $message = false )
 291      {
 292          if ( !is_array( $this->CurrentResult ) )
 293          {
 294               $this->CurrentResult = array( 'status' => $status,
 295                                             'name' => $testName,
 296                                             'messages' => array() );
 297          }
 298          else
 299          {
 300              $this->CurrentResult['status'] = $status;
 301          }
 302          if ( $message or $assertName )
 303              $this->CurrentResult['messages'][] = array( 'assert' => $assertName,
 304                                                          'assert_number' => $this->CurrentAssertNumber,
 305                                                          'text' => $message );
 306      }
 307  
 308      /*!
 309       \protected
 310       Adds the current result to the result list and resets the current result data.
 311      */
 312      function addCurrentResult()
 313      {
 314          if ( is_array( $this->CurrentResult ) )
 315              $this->Results[] = $this->CurrentResult;
 316          return $this->CurrentResult;
 317      }
 318  
 319      /*!
 320       \protected
 321       Resets the current result data.
 322      */
 323      function resetCurrentResult()
 324      {
 325          $this->CurrentResult = array( 'status' => true,
 326                                        'name' => $this->currentTestName(),
 327                                        'messages' => array() );
 328          $this->CurrentAssertNumber = 0;
 329      }
 330  
 331      /*!
 332       \protected
 333       \return \c true if the result of the currently run test is successful.
 334      */
 335      function isCurrentResultSuccessful()
 336      {
 337          if ( !is_array( $this->CurrentResult ) )
 338              return false;
 339          return $this->CurrentResult['status'];
 340      }
 341  
 342      /*!
 343       \return the name of the currently running test or \c false if no test.
 344      */
 345      function currentTestName()
 346      {
 347          return $this->CurrentTestName;
 348      }
 349  
 350      /*!
 351       \protected
 352       Sets the name of the currently running test to \a $name.
 353      */
 354      function setCurrentTestName( $name )
 355      {
 356          $this->CurrentTestName = $name;
 357      }
 358  
 359      /*!
 360       Adds a custom failure with message \a $message.
 361      */
 362      function failure( $message )
 363      {
 364          $this->addToCurrentResult( false, false, $this->currentTestName(), $message );
 365      }
 366  
 367      /*!
 368       Throws an error if \a $assertion is \c false, optionally \a $message may be attached to the failure.
 369      */
 370      function assert( $assertion, $message = false )
 371      {
 372          $this->CurrentAssertNumber++;
 373          if ( !$assertion )
 374              $this->addToCurrentResult( false, 'assert', $this->currentTestName(), $message );
 375      }
 376  
 377      /*!
 378       Throws an error if \a $actual is not equal to \a $expected, optionally \a $message may be attached to the failure.
 379       It will use === for equality checking.
 380      */
 381      function assertEquals( $actual, $expected, $message = false )
 382      {
 383          $this->CurrentAssertNumber++;
 384          if ( $actual !== $expected )
 385              $this->addToCurrentResult( false, 'assertEquals', $this->currentTestName(), $message );
 386      }
 387  
 388      /*!
 389       Throws an error if \a $actual is equal to \a $expected, optionally \a $message may be attached to the failure.
 390       It will use === for unequality checking.
 391      */
 392      function assertNotEquals( $actual, $expected, $message = false )
 393      {
 394          $this->CurrentAssertNumber++;
 395          if ( $actual === $expected )
 396              $this->addToCurrentResult( false, 'assertNotEquals', $this->currentTestName(), $message );
 397      }
 398  
 399      /*!
 400       Throws an error if \a $actual is not simi;ar to \a $expected, optionally \a $message may be attached to the failure.
 401       It will use == for similarity checking.
 402      */
 403      function assertSimilar( $actual, $expected, $message = false )
 404      {
 405          $this->CurrentAssertNumber++;
 406          if ( $actual != $expected )
 407              $this->addToCurrentResult( false, 'assertSimilar', $this->currentTestName(), $message );
 408      }
 409  
 410      /*!
 411       Throws an error if \a $actual is similar to \a $expected, optionally \a $message may be attached to the failure.
 412       It will use == for similarity checking.
 413      */
 414      function assertNotSimilar( $actual, $expected, $message = false )
 415      {
 416          $this->CurrentAssertNumber++;
 417          if ( $actual == $expected )
 418              $this->addToCurrentResult( false, 'assertNotSimilar', $this->currentTestName(), $message );
 419      }
 420  
 421      /// \privatesection
 422      /// An array with test results.
 423      var $Results;
 424      /// The current result
 425      var $CurrentResult;
 426      /// The name of the currently running test or \c false
 427      var $CurrentTestName;
 428      /// Contains the number of the currently run assertion in a test, \c 0 means no assertions are run yet.
 429      var $CurrentAssertNumber;
 430  }
 431  
 432  ?>