Source for file exceptions.php

Documentation is available at exceptions.php

  1. <?php
  2. /**
  3.  *  base include file for SimpleTest
  4.  *  @package    SimpleTest
  5.  *  @subpackage UnitTester
  6.  *  @version    $Id: exceptions.php 1882 2009-07-01 14:30:05Z lastcraft $
  7.  */
  8.  
  9. /**#@+
  10.  * Include required SimpleTest files
  11.  */
  12. require_once dirname(__FILE__) . '/invoker.php';
  13. require_once dirname(__FILE__) . '/expectation.php';
  14. /**#@-*/
  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 __construct($invoker) {
  29.         parent::__construct($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.             $has_thrown = false;
  43.             parent::invoke($method);
  44.         } catch (Exception $exception) {
  45.             $has_thrown = true;
  46.             if (! $trap->isExpected($this->getTestCase(), $exception)) {
  47.                 $this->getTestCase()->exception($exception);
  48.             }
  49.             $trap->clear();
  50.         }
  51.         if ($message = $trap->getOutstanding()) {
  52.             $this->getTestCase()->fail($message);
  53.         }
  54.         if ($has_thrown) {
  55.             try {
  56.                 parent::getTestCase()->tearDown();
  57.             } catch (Exception $e) { }
  58.         }
  59.     }
  60. }
  61.  
  62. /**
  63.  *    Tests exceptions either by type or the exact
  64.  *    exception. This could be improved to accept
  65.  *    a pattern expectation to test the error
  66.  *    message, but that will have to come later.
  67.  *    @package SimpleTest
  68.  *    @subpackage UnitTester
  69.  */
  70. class ExceptionExpectation extends SimpleExpectation {
  71.     private $expected;
  72.  
  73.     /**
  74.      *    Sets up the conditions to test against.
  75.      *    If the expected value is a string, then
  76.      *    it will act as a test of the class name.
  77.      *    An exception as the comparison will
  78.      *    trigger an identical match. Writing this
  79.      *    down now makes it look doubly dumb. I hope
  80.      *    come up with a better scheme later.
  81.      *    @param mixed $expected   A class name or an actual
  82.      *                              exception to compare with.
  83.      *    @param string $message   Message to display.
  84.      */
  85.     function __construct($expected, $message = '%s') {
  86.         $this->expected = $expected;
  87.         parent::__construct($message);
  88.     }
  89.  
  90.     /**
  91.      *    Carry out the test.
  92.      *    @param Exception $compare    Value to check.
  93.      *    @return boolean              True if matched.
  94.      */
  95.     function test($compare) {
  96.         if (is_string($this->expected)) {
  97.             return ($compare instanceof $this->expected);
  98.         }
  99.         if (get_class($compare) != get_class($this->expected)) {
  100.             return false;
  101.         }
  102.         return $compare->getMessage() == $this->expected->getMessage();
  103.     }
  104.  
  105.     /**
  106.      *    Create the message to display describing the test.
  107.      *    @param Exception $compare     Exception to match.
  108.      *    @return string                Final message.
  109.      */
  110.     function testMessage($compare) {
  111.         if (is_string($this->expected)) {
  112.             return "Exception [" . $this->describeException($compare) .
  113.                     "] should be type [" . $this->expected . "]";
  114.         }
  115.         return "Exception [" . $this->describeException($compare) .
  116.                 "] should match [" .
  117.                 $this->describeException($this->expected) . "]";
  118.     }
  119.  
  120.     /**
  121.      *    Summary of an Exception object.
  122.      *    @param Exception $compare     Exception to describe.
  123.      *    @return string                Text description.
  124.      */
  125.     protected function describeException($exception) {
  126.         return get_class($exception) . ": " . $exception->getMessage();
  127.     }
  128. }
  129.  
  130. /**
  131.  *    Stores expected exceptions for when they
  132.  *    get thrown. Saves the irritating try...catch
  133.  *    block.
  134.  *    @package  SimpleTest
  135.  *    @subpackage   UnitTester
  136.  */
  137. class SimpleExceptionTrap {
  138.     private $expected;
  139.     private $ignored;
  140.     private $message;
  141.  
  142.     /**
  143.      *    Clears down the queue ready for action.
  144.      */
  145.     function __construct() {
  146.         $this->clear();
  147.     }
  148.  
  149.     /**
  150.      *    Sets up an expectation of an exception.
  151.      *    This has the effect of intercepting an
  152.      *    exception that matches.
  153.      *    @param SimpleExpectation $expected    Expected exception to match.
  154.      *    @param string $message                Message to display.
  155.      *    @access public
  156.      */
  157.     function expectException($expected = false, $message = '%s') {
  158.         $this->expected = $this->coerceToExpectation($expected);
  159.         $this->message = $message;
  160.     }
  161.  
  162.     /**
  163.      *    Adds an exception to the ignore list. This is the list
  164.      *    of exceptions that when thrown do not affect the test.
  165.      *    @param SimpleExpectation $ignored    Exception to skip.
  166.      *    @access public
  167.      */
  168.     function ignoreException($ignored) {
  169.         $this->ignored[] = $this->coerceToExpectation($ignored);
  170.     }
  171.  
  172.     /**
  173.      *    Compares the expected exception with any
  174.      *    in the queue. Issues a pass or fail and
  175.      *    returns the state of the test.
  176.      *    @param SimpleTestCase $test    Test case to send messages to.
  177.      *    @param Exception $exception    Exception to compare.
  178.      *    @return boolean                False on no match.
  179.      */
  180.     function isExpected($test, $exception) {
  181.         if ($this->expected) {
  182.             return $test->assert($this->expected, $exception, $this->message);
  183.         }
  184.         foreach ($this->ignored as $ignored) {
  185.             if ($ignored->test($exception)) {
  186.                 return true;
  187.             }
  188.         }
  189.         return false;
  190.     }
  191.  
  192.     /**
  193.      *    Turns an expected exception into a SimpleExpectation object.
  194.      *    @param mixed $exception      Exception, expectation or
  195.      *                                  class name of exception.
  196.      *    @return SimpleExpectation    Expectation that will match the
  197.      *                                  exception.
  198.      */
  199.     private function coerceToExpectation($exception) {
  200.         if ($exception === false) {
  201.             return new AnythingExpectation();
  202.         }
  203.         if (! SimpleExpectation::isExpectation($exception)) {
  204.             return new ExceptionExpectation($exception);
  205.         }
  206.         return $exception;
  207.     }
  208.  
  209.     /**
  210.      *    Tests for any left over exception.
  211.      *    @return string/false     The failure message or false if none.
  212.      */
  213.     function getOutstanding() {
  214.         return sprintf($this->message, 'Failed to trap exception');
  215.     }
  216.  
  217.     /**
  218.      *    Discards the contents of the error queue.
  219.      */
  220.     function clear() {
  221.         $this->expected = false;
  222.         $this->message = false;
  223.         $this->ignored = array();
  224.     }
  225. }
  226. ?>

Documentation generated on Sun, 31 Oct 2010 16:31:23 -0500 by phpDocumentor 1.4.3