lib/simpletestlib/unit_tester.php

   1 <?php
   2     /**
   3      *  base include file for SimpleTest
   4      *  @package        SimpleTest
   5      *  @subpackage     UnitTester
   6      *  @version        $Id$
   7      */
   8
   9     /**#@+
  10      *  include other SimpleTest class files
  11      */
  12     require_once(dirname(__FILE__) . '/test_case.php');
  13     require_once(dirname(__FILE__) . '/dumper.php');
  14     /**#@-*/
  15
  16     /**
  17      *    Standard unit test class for day to day testing
  18      *    of PHP code XP style. Adds some useful standard
  19      *    assertions.
  20          *        @package      SimpleTest
  21          *        @subpackage   UnitTester
  22      */
  23     class UnitTestCase extends SimpleTestCase {
  24
  25         /**
  26          *    Creates an empty test case. Should be subclassed
  27          *    with test methods for a functional test case.
  28          *    @param string $label     Name of test case. Will use
  29          *                             the class name if none specified.
  30          *    @access public
  31          */
  32         function UnitTestCase($label = false) {
  33             if (! $label) {
  34                 $label = get_class($this);
  35             }
  36             $this->SimpleTestCase($label);
  37         }
  38
  39         /**
  40          *    Called from within the test methods to register
  41          *    passes and failures.
  42          *    @param boolean $result    Pass on true.
  43          *    @param string $message    Message to display describing
  44          *                              the test state.
  45          *    @return boolean           True on pass
  46          *    @access public
  47          */
  48         function assertTrue($result, $message = false) {
  49             return $this->assert(new TrueExpectation(), $result, $message);
  50         }
  51
  52         /**
  53          *    Will be true on false and vice versa. False
  54          *    is the PHP definition of false, so that null,
  55          *    empty strings, zero and an empty array all count
  56          *    as false.
  57          *    @param boolean $result    Pass on false.
  58          *    @param string $message    Message to display.
  59          *    @return boolean           True on pass
  60          *    @access public
  61          */
  62         function assertFalse($result, $message = '%s') {
  63             return $this->assert(new FalseExpectation(), $result, $message);
  64         }
  65
  66         /**
  67          *    Will be true if the value is null.
  68          *    @param null $value       Supposedly null value.
  69          *    @param string $message   Message to display.
  70          *    @return boolean                        True on pass
  71          *    @access public
  72          */
  73         function assertNull($value, $message = '%s') {
  74             $dumper = &new SimpleDumper();
  75             $message = sprintf(
  76                     $message,
  77                     '[' . $dumper->describeValue($value) . '] should be null');
  78             return $this->assertTrue(! isset($value), $message);
  79         }
  80
  81         /**
  82          *    Will be true if the value is set.
  83          *    @param mixed $value           Supposedly set value.
  84          *    @param string $message        Message to display.
  85          *    @return boolean               True on pass.
  86          *    @access public
  87          */
  88         function assertNotNull($value, $message = '%s') {
  89             $dumper = &new SimpleDumper();
  90             $message = sprintf(
  91                     $message,
  92                     '[' . $dumper->describeValue($value) . '] should not be null');
  93             return $this->assertTrue(isset($value), $message);
  94         }
  95
  96         /**
  97          *    Type and class test. Will pass if class
  98          *    matches the type name or is a subclass or
  99          *    if not an object, but the type is correct.
 100          *    @param mixed $object         Object to test.
 101          *    @param string $type          Type name as string.
 102          *    @param string $message       Message to display.
 103          *    @return boolean              True on pass.
 104          *    @access public
 105          */
 106         function assertIsA($object, $type, $message = '%s') {
 107             return $this->assert(
 108                     new IsAExpectation($type),
 109                     $object,
 110                     $message);
 111         }
 112
 113         /**
 114          *    Type and class mismatch test. Will pass if class
 115          *    name or underling type does not match the one
 116          *    specified.
 117          *    @param mixed $object         Object to test.
 118          *    @param string $type          Type name as string.
 119          *    @param string $message       Message to display.
 120          *    @return boolean              True on pass.
 121          *    @access public
 122          */
 123         function assertNotA($object, $type, $message = '%s') {
 124             return $this->assert(
 125                     new NotAExpectation($type),
 126                     $object,
 127                     $message);
 128         }
 129
 130         /**
 131          *    Will trigger a pass if the two parameters have
 132          *    the same value only. Otherwise a fail.
 133          *    @param mixed $first          Value to compare.
 134          *    @param mixed $second         Value to compare.
 135          *    @param string $message       Message to display.
 136          *    @return boolean              True on pass
 137          *    @access public
 138          */
 139         function assertEqual($first, $second, $message = '%s') {
 140             return $this->assert(
 141                     new EqualExpectation($first),
 142                     $second,
 143                     $message);
 144         }
 145
 146         /**
 147          *    Will trigger a pass if the two parameters have
 148          *    a different value. Otherwise a fail.
 149          *    @param mixed $first           Value to compare.
 150          *    @param mixed $second          Value to compare.
 151          *    @param string $message        Message to display.
 152          *    @return boolean               True on pass
 153          *    @access public
 154          */
 155         function assertNotEqual($first, $second, $message = '%s') {
 156             return $this->assert(
 157                     new NotEqualExpectation($first),
 158                     $second,
 159                     $message);
 160         }
 161
 162         /**
 163          *    Will trigger a pass if the if the first parameter
 164          *    is near enough to the second by the margin.
 165          *    @param mixed $first          Value to compare.
 166          *    @param mixed $second         Value to compare.
 167          *    @param mixed $margin         Fuzziness of match.
 168          *    @param string $message       Message to display.
 169          *    @return boolean              True on pass
 170          *    @access public
 171          */
 172         function assertWithinMargin($first, $second, $margin, $message = '%s') {
 173             return $this->assert(
 174                     new WithinMarginExpectation($first, $margin),
 175                     $second,
 176                     $message);
 177         }
 178
 179         /**
 180          *    Will trigger a pass if the two parameters differ
 181          *    by more than the margin.
 182          *    @param mixed $first          Value to compare.
 183          *    @param mixed $second         Value to compare.
 184          *    @param mixed $margin         Fuzziness of match.
 185          *    @param string $message       Message to display.
 186          *    @return boolean              True on pass
 187          *    @access public
 188          */
 189         function assertOutsideMargin($first, $second, $margin, $message = '%s') {
 190             return $this->assert(
 191                     new OutsideMarginExpectation($first, $margin),
 192                     $second,
 193                     $message);
 194         }
 195
 196         /**
 197          *    Will trigger a pass if the two parameters have
 198          *    the same value and same type. Otherwise a fail.
 199          *    @param mixed $first           Value to compare.
 200          *    @param mixed $second          Value to compare.
 201          *    @param string $message        Message to display.
 202          *    @return boolean               True on pass
 203          *    @access public
 204          */
 205         function assertIdentical($first, $second, $message = '%s') {
 206             return $this->assert(
 207                     new IdenticalExpectation($first),
 208                     $second,
 209                     $message);
 210         }
 211
 212         /**
 213          *    Will trigger a pass if the two parameters have
 214          *    the different value or different type.
 215          *    @param mixed $first           Value to compare.
 216          *    @param mixed $second          Value to compare.
 217          *    @param string $message        Message to display.
 218          *    @return boolean               True on pass
 219          *    @access public
 220          */
 221         function assertNotIdentical($first, $second, $message = '%s') {
 222             return $this->assert(
 223                     new NotIdenticalExpectation($first),
 224                     $second,
 225                     $message);
 226         }
 227
 228         /**
 229          *    Will trigger a pass if both parameters refer
 230          *    to the same object. Fail otherwise.
 231          *    @param mixed $first           Object reference to check.
 232          *    @param mixed $second          Hopefully the same object.
 233          *    @param string $message        Message to display.
 234          *    @return boolean               True on pass
 235          *    @access public
 236          */
 237         function assertReference(&$first, &$second, $message = '%s') {
 238             $dumper = &new SimpleDumper();
 239             $message = sprintf(
 240                     $message,
 241                     '[' . $dumper->describeValue($first) .
 242                             '] and [' . $dumper->describeValue($second) .
 243                             '] should reference the same object');
 244             return $this->assertTrue(
 245                     SimpleTestCompatibility::isReference($first, $second),
 246                     $message);
 247         }
 248
 249         /**
 250          *    Will trigger a pass if both parameters refer
 251          *    to different objects. Fail otherwise. The objects
 252          *    have to be identical though.
 253          *    @param mixed $first           Object reference to check.
 254          *    @param mixed $second          Hopefully not the same object.
 255          *    @param string $message        Message to display.
 256          *    @return boolean               True on pass
 257          *    @access public
 258          */
 259         function assertClone(&$first, &$second, $message = '%s') {
 260             $dumper = &new SimpleDumper();
 261             $message = sprintf(
 262                     $message,
 263                     '[' . $dumper->describeValue($first) .
 264                             '] and [' . $dumper->describeValue($second) .
 265                             '] should not be the same object');
 266             $identical = &new IdenticalExpectation($first);
 267             return $this->assertTrue(
 268                     $identical->test($second) &&
 269                             ! SimpleTestCompatibility::isReference($first, $second),
 270                     $message);
 271         }
 272
 273         /**
 274          *    @deprecated
 275          */
 276         function assertCopy(&$first, &$second, $message = "%s") {
 277             $dumper = &new SimpleDumper();
 278             $message = sprintf(
 279                     $message,
 280                     "[" . $dumper->describeValue($first) .
 281                             "] and [" . $dumper->describeValue($second) .
 282                             "] should not be the same object");
 283             return $this->assertFalse(
 284                     SimpleTestCompatibility::isReference($first, $second),
 285                     $message);
 286         }
 287
 288         /**
 289          *    Will trigger a pass if the Perl regex pattern
 290          *    is found in the subject. Fail otherwise.
 291          *    @param string $pattern    Perl regex to look for including
 292          *                              the regex delimiters.
 293          *    @param string $subject    String to search in.
 294          *    @param string $message    Message to display.
 295          *    @return boolean           True on pass
 296          *    @access public
 297          */
 298         function assertPattern($pattern, $subject, $message = '%s') {
 299             return $this->assert(
 300                     new PatternExpectation($pattern),
 301                     $subject,
 302                     $message);
 303         }
 304
 305         /**
 306          *        @deprecated
 307          */
 308         function assertWantedPattern($pattern, $subject, $message = '%s') {
 309                 return $this->assertPattern($pattern, $subject, $message);
 310         }
 311
 312         /**
 313          *    Will trigger a pass if the perl regex pattern
 314          *    is not present in subject. Fail if found.
 315          *    @param string $pattern    Perl regex to look for including
 316          *                              the regex delimiters.
 317          *    @param string $subject    String to search in.
 318          *    @param string $message    Message to display.
 319          *    @return boolean           True on pass
 320          *    @access public
 321          */
 322         function assertNoPattern($pattern, $subject, $message = '%s') {
 323             return $this->assert(
 324                     new NoPatternExpectation($pattern),
 325                     $subject,
 326                     $message);
 327         }
 328
 329         /**
 330          *        @deprecated
 331          */
 332         function assertNoUnwantedPattern($pattern, $subject, $message = '%s') {
 333                 return $this->assertNoPattern($pattern, $subject, $message);
 334         }
 335
 336         /**
 337          *    @deprecated
 338          */
 339         function swallowErrors() {
 340             $context = &SimpleTest::getContext();
 341             $queue = &$context->get('SimpleErrorQueue');
 342             $queue->clear();
 343         }
 344
 345         /**
 346          *    @deprecated
 347          */
 348         function assertNoErrors($message = '%s') {
 349             $context = &SimpleTest::getContext();
 350             $queue = &$context->get('SimpleErrorQueue');
 351             return $queue->assertNoErrors($message);
 352         }
 353
 354         /**
 355          *    @deprecated
 356          */
 357         function assertError($expected = false, $message = '%s') {
 358             $context = &SimpleTest::getContext();
 359             $queue = &$context->get('SimpleErrorQueue');
 360             return $queue->assertError($this->_coerceExpectation($expected), $message);
 361         }
 362
 363         /**
 364          *    Prepares for an error. If the error mismatches it
 365          *    passes through, otherwise it is swallowed. Any
 366          *    left over errors trigger failures.
 367          *    @param SimpleExpectation/string $expected   The error to match.
 368          *    @param string $message                      Message on failure.
 369          *    @access public
 370          */
 371         function expectError($expected = false, $message = '%s') {
 372             $context = &SimpleTest::getContext();
 373             $queue = &$context->get('SimpleErrorQueue');
 374             $queue->expectError($this->_coerceExpectation($expected), $message);
 375         }
 376
 377         /**
 378          *    Prepares for an exception. If the error mismatches it
 379          *    passes through, otherwise it is swallowed. Any
 380          *    left over errors trigger failures.
 381          *    @param SimpleExpectation/Exception $expected  The error to match.
 382          *    @param string $message                        Message on failure.
 383          *    @access public
 384          */
 385         function expectException($expected = false, $message = '%s') {
 386             $context = &SimpleTest::getContext();
 387             $queue = &$context->get('SimpleExceptionTrap');
 388             $queue->expectException($expected, $message . $this->getAssertionLine());
 389         }
 390
 391         /**
 392          *    Creates an equality expectation if the
 393          *    object/value is not already some type
 394          *    of expectation.
 395          *    @param mixed $expected      Expected value.
 396          *    @return SimpleExpectation   Expectation object.
 397          *    @access private
 398          */
 399         function _coerceExpectation($expected) {
 400             if ($expected == false) {
 401                 return new AnythingExpectation();
 402             }
 403             if (SimpleTestCompatibility::isA($expected, 'SimpleExpectation')) {
 404                 return $expected;
 405             }
 406                         if(is_string($expected)) {
 407                                 $expected = str_replace('%', '%%', $expected);
 408                         }
 409             return new EqualExpectation($expected);
 410         }
 411
 412         /**
 413          *    @deprecated
 414          */
 415         function assertErrorPattern($pattern, $message = '%s') {
 416             return $this->assertError(new PatternExpectation($pattern), $message);
 417         }
 418     }
 419 ?>