lib/simpletestlib/exceptions.php

   1 <?php
   2     /**
   3      *  base include file for SimpleTest
   4      *  @package        SimpleTest
   5      *  @subpackage     UnitTester
   6      *  @version        $Id$
   7      */
   8
   9     /**#@+
  10      * Includes SimpleTest files and defined the root constant
  11      * for dependent libraries.
  12      */
  13     require_once(dirname(__FILE__) . '/invoker.php');
  14     require_once(dirname(__FILE__) . '/expectation.php');
  15
  16     /**
  17      *    Extension that traps exceptions and turns them into
  18      *    an error message. PHP5 only.
  19          *        @package SimpleTest
  20          *        @subpackage UnitTester
  21      */
  22     class SimpleExceptionTrappingInvoker extends SimpleInvokerDecorator {
  23
  24         /**
  25          *    Stores the invoker to be wrapped.
  26          *    @param SimpleInvoker $invoker   Test method runner.
  27          */
  28         function SimpleExceptionTrappingInvoker($invoker) {
  29             $this->SimpleInvokerDecorator($invoker);
  30         }
  31
  32         /**
  33          *    Invokes a test method whilst trapping expected
  34          *    exceptions. Any left over unthrown exceptions
  35          *    are then reported as failures.
  36          *    @param string $method    Test method to call.
  37          */
  38         function invoke($method) {
  39             $trap = SimpleTest::getContext()->get('SimpleExceptionTrap');
  40             $trap->clear();
  41             try {
  42                 parent::invoke($method);
  43             } catch (Exception $exception) {
  44                     if (! $trap->isExpected($this->getTestCase(), $exception)) {
  45                         $this->getTestCase()->exception($exception);
  46                     }
  47                     $trap->clear();
  48             }
  49                         if ($message = $trap->getOutstanding()) {
  50                                 $this->getTestCase()->fail($message);
  51                         }
  52         }
  53     }
  54
  55     /**
  56      *    Tests exceptions either by type or the exact
  57      *    exception. This could be improved to accept
  58      *    a pattern expectation to test the error
  59      *    message, but that will have to come later.
  60          *        @package SimpleTest
  61          *        @subpackage UnitTester
  62      */
  63     class ExceptionExpectation extends SimpleExpectation {
  64         private $expected;
  65
  66         /**
  67          *    Sets up the conditions to test against.
  68          *    If the expected value is a string, then
  69          *    it will act as a test of the class name.
  70          *    An exception as the comparison will
  71          *    trigger an identical match. Writing this
  72          *    down now makes it look doubly dumb. I hope
  73          *    come up with a better scheme later.
  74          *    @param mixed $expected   A class name or an actual
  75          *                             exception to compare with.
  76          *    @param string $message   Message to display.
  77          */
  78         function __construct($expected, $message = '%s') {
  79             $this->expected = $expected;
  80             parent::__construct($message);
  81         }
  82
  83         /**
  84          *    Carry out the test.
  85          *    @param Exception $compare    Value to check.
  86          *    @return boolean              True if matched.
  87          */
  88         function test($compare) {
  89             if (is_string($this->expected)) {
  90                 return ($compare instanceof $this->expected);
  91             }
  92             if (get_class($compare) != get_class($this->expected)) {
  93                 return false;
  94             }
  95             return $compare->getMessage() == $this->expected->getMessage();
  96         }
  97
  98         /**
  99          *    Create the message to display describing the test.
 100          *    @param Exception $compare     Exception to match.
 101          *    @return string                Final message.
 102          */
 103         function testMessage($compare) {
 104             if (is_string($this->expected)) {
 105                 return "Exception [" . $this->describeException($compare) .
 106                         "] should be type [" . $this->expected . "]";
 107             }
 108             return "Exception [" . $this->describeException($compare) .
 109                     "] should match [" .
 110                     $this->describeException($this->expected) . "]";
 111         }
 112
 113         /**
 114          *    Summary of an Exception object.
 115          *    @param Exception $compare     Exception to describe.
 116          *    @return string                Text description.
 117          */
 118         protected function describeException($exception) {
 119             return get_class($exception) . ": " . $exception->getMessage();
 120         }
 121     }
 122
 123     /**
 124      *    Stores expected exceptions for when they
 125      *    get thrown. Saves the irritating try...catch
 126      *    block.
 127          *        @package      SimpleTest
 128          *        @subpackage   UnitTester
 129      */
 130     class SimpleExceptionTrap {
 131         private $expected;
 132         private $message;
 133
 134         /**
 135          *    Clears down the queue ready for action.
 136          */
 137         function __construct() {
 138             $this->clear();
 139         }
 140
 141         /**
 142          *    Sets up an expectation of an exception.
 143          *    This has the effect of intercepting an
 144          *    exception that matches.
 145          *    @param SimpleExpectation $expected    Expected exception to match.
 146          *    @param string $message                Message to display.
 147          *    @access public
 148          */
 149         function expectException($expected = false, $message = '%s') {
 150             if ($expected === false) {
 151                 $expected = new AnythingExpectation();
 152             }
 153             if (! SimpleExpectation::isExpectation($expected)) {
 154                 $expected = new ExceptionExpectation($expected);
 155             }
 156             $this->expected = $expected;
 157             $this->message = $message;
 158         }
 159
 160         /**
 161          *    Compares the expected exception with any
 162          *    in the queue. Issues a pass or fail and
 163          *    returns the state of the test.
 164          *    @param SimpleTestCase $test    Test case to send messages to.
 165          *    @param Exception $exception    Exception to compare.
 166          *    @return boolean                False on no match.
 167          */
 168         function isExpected($test, $exception) {
 169             if ($this->expected) {
 170                     return $test->assert($this->expected, $exception, $this->message);
 171             }
 172                         return false;
 173         }
 174
 175                 /**
 176                  *    Tests for any left over exception.
 177                  *    @return string/false     The failure message or false if none.
 178                  */
 179                 function getOutstanding() {
 180                         return sprintf($this->message, 'Failed to trap exception');
 181                 }
 182
 183         /**
 184          *    Discards the contents of the error queue.
 185          */
 186         function clear() {
 187             $this->expected = false;
 188             $this->message = false;
 189         }
 190     }
 191 ?>