tests/PHPUnit/PHPUnit/Framework/TestCase.php

   1 <?php
   2 /**
   3  * PHPUnit
   4  *
   5  * Copyright (c) 2002-2011, Sebastian Bergmann <sebastian@phpunit.de>.
   6  * All rights reserved.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  *
  12  *   * Redistributions of source code must retain the above copyright
  13  *     notice, this list of conditions and the following disclaimer.
  14  *
  15  *   * Redistributions in binary form must reproduce the above copyright
  16  *     notice, this list of conditions and the following disclaimer in
  17  *     the documentation and/or other materials provided with the
  18  *     distribution.
  19  *
  20  *   * Neither the name of Sebastian Bergmann nor the names of his
  21  *     contributors may be used to endorse or promote products derived
  22  *     from this software without specific prior written permission.
  23  *
  24  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  25  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  26  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  27  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  28  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  29  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  30  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  32  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  34  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  35  * POSSIBILITY OF SUCH DAMAGE.
  36  *
  37  * @package    PHPUnit
  38  * @subpackage Framework
  39  * @author     Sebastian Bergmann <sebastian@phpunit.de>
  40  * @copyright  2002-2011 Sebastian Bergmann <sebastian@phpunit.de>
  41  * @license    http://www.opensource.org/licenses/bsd-license.php  BSD License
  42  * @link       http://www.phpunit.de/
  43  * @since      File available since Release 2.0.0
  44  */
  45
  46 require_once 'Text/Template.php';
  47
  48 /**
  49  * A TestCase defines the fixture to run multiple tests.
  50  *
  51  * To define a TestCase
  52  *
  53  *   1) Implement a subclass of PHPUnit_Framework_TestCase.
  54  *   2) Define instance variables that store the state of the fixture.
  55  *   3) Initialize the fixture state by overriding setUp().
  56  *   4) Clean-up after a test by overriding tearDown().
  57  *
  58  * Each test runs in its own fixture so there can be no side effects
  59  * among test runs.
  60  *
  61  * Here is an example:
  62  *
  63  * <code>
  64  * <?php
  65  * class MathTest extends PHPUnit_Framework_TestCase
  66  * {
  67  *     public $value1;
  68  *     public $value2;
  69  *
  70  *     protected function setUp()
  71  *     {
  72  *         $this->value1 = 2;
  73  *         $this->value2 = 3;
  74  *     }
  75  * }
  76  * ?>
  77  * </code>
  78  *
  79  * For each test implement a method which interacts with the fixture.
  80  * Verify the expected results with assertions specified by calling
  81  * assert with a boolean.
  82  *
  83  * <code>
  84  * <?php
  85  * public function testPass()
  86  * {
  87  *     $this->assertTrue($this->value1 + $this->value2 == 5);
  88  * }
  89  * ?>
  90  * </code>
  91  *
  92  * @package    PHPUnit
  93  * @subpackage Framework
  94  * @author     Sebastian Bergmann <sebastian@phpunit.de>
  95  * @copyright  2002-2011 Sebastian Bergmann <sebastian@phpunit.de>
  96  * @license    http://www.opensource.org/licenses/bsd-license.php  BSD License
  97  * @version    Release: 3.5.13
  98  * @link       http://www.phpunit.de/
  99  * @since      Class available since Release 2.0.0
 100  */
 101 abstract class PHPUnit_Framework_TestCase extends PHPUnit_Framework_Assert implements PHPUnit_Framework_Test, PHPUnit_Framework_SelfDescribing
 102 {
 103     /**
 104      * Enable or disable the backup and restoration of the $GLOBALS array.
 105      * Overwrite this attribute in a child class of TestCase.
 106      * Setting this attribute in setUp() has no effect!
 107      *
 108      * @var    boolean
 109      */
 110     protected $backupGlobals = NULL;
 111
 112     /**
 113      * @var    array
 114      */
 115     protected $backupGlobalsBlacklist = array();
 116
 117     /**
 118      * Enable or disable the backup and restoration of static attributes.
 119      * Overwrite this attribute in a child class of TestCase.
 120      * Setting this attribute in setUp() has no effect!
 121      *
 122      * @var    boolean
 123      */
 124     protected $backupStaticAttributes = NULL;
 125
 126     /**
 127      * @var    array
 128      */
 129     protected $backupStaticAttributesBlacklist = array();
 130
 131     /**
 132      * Whether or not this test is to be run in a separate PHP process.
 133      *
 134      * @var    boolean
 135      */
 136     protected $runTestInSeparateProcess = NULL;
 137
 138     /**
 139      * Whether or not this test should preserve the global state when
 140      * running in a separate PHP process.
 141      *
 142      * @var    boolean
 143      */
 144     protected $preserveGlobalState = TRUE;
 145
 146     /**
 147      * Whether or not this test is running in a separate PHP process.
 148      *
 149      * @var    boolean
 150      */
 151     private $inIsolation = FALSE;
 152
 153     /**
 154      * @var    array
 155      */
 156     private $data = array();
 157
 158     /**
 159      * @var    string
 160      */
 161     private $dataName = '';
 162
 163     /**
 164      * @var    boolean
 165      */
 166     private $useErrorHandler = NULL;
 167
 168     /**
 169      * @var    boolean
 170      */
 171     private $useOutputBuffering = NULL;
 172
 173     /**
 174      * The name of the expected Exception.
 175      *
 176      * @var    mixed
 177      */
 178     private $expectedException = NULL;
 179
 180     /**
 181      * The message of the expected Exception.
 182      *
 183      * @var    string
 184      */
 185     private $expectedExceptionMessage = '';
 186
 187     /**
 188      * The code of the expected Exception.
 189      *
 190      * @var    integer
 191      */
 192     private $expectedExceptionCode;
 193
 194     /**
 195      * The stack trace to where the expected exception was set.
 196      *
 197      * @var    array
 198      */
 199     private $expectedExceptionTrace = array();
 200
 201     /**
 202      * The name of the test case.
 203      *
 204      * @var    string
 205      */
 206     private $name = NULL;
 207
 208     /**
 209      * @var    array
 210      */
 211     private $dependencies = array();
 212
 213     /**
 214      * @var    array
 215      */
 216     private $dependencyInput = array();
 217
 218     /**
 219      * @var    string
 220      */
 221     private $exceptionMessage = NULL;
 222
 223     /**
 224      * @var    integer
 225      */
 226     private $exceptionCode = 0;
 227
 228     /**
 229      * @var    Array
 230      */
 231     private $iniSettings = array();
 232
 233     /**
 234      * @var    Array
 235      */
 236     private $locale = array();
 237
 238     /**
 239      * @var    Array
 240      */
 241     private $mockObjects = array();
 242
 243     /**
 244      * @var    integer
 245      */
 246     private $status;
 247
 248     /**
 249      * @var    string
 250      */
 251     private $statusMessage = '';
 252
 253     /**
 254      * @var    integer
 255      */
 256     private $numAssertions = 0;
 257
 258     /**
 259      * @var PHPUnit_Framework_TestResult
 260      */
 261     private $result;
 262
 263     /**
 264      * @var mixed
 265      */
 266     private $testResult;
 267
 268     /**
 269      * Constructs a test case with the given name.
 270      *
 271      * @param  string $name
 272      * @param  array  $data
 273      * @param  string $dataName
 274      */
 275     public function __construct($name = NULL, array $data = array(), $dataName = '')
 276     {
 277         if ($name !== NULL) {
 278             $this->setName($name);
 279         }
 280
 281         $this->data     = $data;
 282         $this->dataName = $dataName;
 283     }
 284
 285     /**
 286      * Returns a string representation of the test case.
 287      *
 288      * @return string
 289      */
 290     public function toString()
 291     {
 292         $class = new ReflectionClass($this);
 293
 294         $buffer = sprintf(
 295           '%s::%s',
 296
 297           $class->name,
 298           $this->getName(FALSE)
 299         );
 300
 301         return $buffer . $this->getDataSetAsString();
 302     }
 303
 304     /**
 305      * Counts the number of test cases executed by run(TestResult result).
 306      *
 307      * @return integer
 308      */
 309     public function count()
 310     {
 311         return 1;
 312     }
 313
 314     /**
 315      * Returns the annotations for this test.
 316      *
 317      * @return array
 318      * @since Method available since Release 3.4.0
 319      */
 320     public function getAnnotations()
 321     {
 322         return PHPUnit_Util_Test::parseTestMethodAnnotations(
 323           get_class($this), $this->name
 324         );
 325     }
 326
 327     /**
 328      * Gets the name of a TestCase.
 329      *
 330      * @param  boolean $withDataSet
 331      * @return string
 332      */
 333     public function getName($withDataSet = TRUE)
 334     {
 335         if ($withDataSet) {
 336             return $this->name . $this->getDataSetAsString(FALSE);
 337         } else {
 338             return $this->name;
 339         }
 340     }
 341
 342     /**
 343      * @return string
 344      * @since  Method available since Release 3.2.0
 345      */
 346     public function getExpectedException()
 347     {
 348         return $this->expectedException;
 349     }
 350
 351     /**
 352      * @param  mixed   $exceptionName
 353      * @param  string  $exceptionMessage
 354      * @param  integer $exceptionCode
 355      * @since  Method available since Release 3.2.0
 356      */
 357     public function setExpectedException($exceptionName, $exceptionMessage = '', $exceptionCode = 0)
 358     {
 359         $this->expectedException        = $exceptionName;
 360         $this->expectedExceptionMessage = $exceptionMessage;
 361         $this->expectedExceptionCode    = $exceptionCode;
 362         $this->expectedExceptionTrace   = debug_backtrace();
 363     }
 364
 365     /**
 366      * @since  Method available since Release 3.4.0
 367      */
 368     protected function setExpectedExceptionFromAnnotation()
 369     {
 370         try {
 371             $expectedException = PHPUnit_Util_Test::getExpectedException(
 372               get_class($this), $this->name
 373             );
 374
 375             if ($expectedException !== FALSE) {
 376                 $this->setExpectedException(
 377                   $expectedException['class'],
 378                   $expectedException['message'],
 379                   $expectedException['code']
 380                 );
 381             }
 382         }
 383
 384         catch (ReflectionException $e) {
 385         }
 386     }
 387
 388     /**
 389      * @param boolean $useErrorHandler
 390      * @since Method available since Release 3.4.0
 391      */
 392     public function setUseErrorHandler($useErrorHandler)
 393     {
 394         $this->useErrorHandler = $useErrorHandler;
 395     }
 396
 397     /**
 398      * @since Method available since Release 3.4.0
 399      */
 400     protected function setUseErrorHandlerFromAnnotation()
 401     {
 402         try {
 403             $useErrorHandler = PHPUnit_Util_Test::getErrorHandlerSettings(
 404               get_class($this), $this->name
 405             );
 406
 407             if ($useErrorHandler !== NULL) {
 408                 $this->setUseErrorHandler($useErrorHandler);
 409             }
 410         }
 411
 412         catch (ReflectionException $e) {
 413         }
 414     }
 415
 416     /**
 417      * @param boolean $useOutputBuffering
 418      * @since Method available since Release 3.4.0
 419      */
 420     public function setUseOutputBuffering($useOutputBuffering)
 421     {
 422         $this->useOutputBuffering = $useOutputBuffering;
 423     }
 424
 425     /**
 426      * @since Method available since Release 3.4.0
 427      */
 428     protected function setUseOutputBufferingFromAnnotation()
 429     {
 430         try {
 431             $useOutputBuffering = PHPUnit_Util_Test::getOutputBufferingSettings(
 432               get_class($this), $this->name
 433             );
 434
 435             if ($useOutputBuffering !== NULL) {
 436                 $this->setUseOutputBuffering($useOutputBuffering);
 437             }
 438         }
 439
 440         catch (ReflectionException $e) {
 441         }
 442     }
 443
 444     /**
 445      * Returns the status of this test.
 446      *
 447      * @return integer
 448      * @since  Method available since Release 3.1.0
 449      */
 450     public function getStatus()
 451     {
 452         return $this->status;
 453     }
 454
 455     /**
 456      * Returns the status message of this test.
 457      *
 458      * @return string
 459      * @since  Method available since Release 3.3.0
 460      */
 461     public function getStatusMessage()
 462     {
 463         return $this->statusMessage;
 464     }
 465
 466     /**
 467      * Returns whether or not this test has failed.
 468      *
 469      * @return boolean
 470      * @since  Method available since Release 3.0.0
 471      */
 472     public function hasFailed()
 473     {
 474         $status = $this->getStatus();
 475
 476         return $status == PHPUnit_Runner_BaseTestRunner::STATUS_FAILURE ||
 477                $status == PHPUnit_Runner_BaseTestRunner::STATUS_ERROR;
 478     }
 479
 480     /**
 481      * Runs the test case and collects the results in a TestResult object.
 482      * If no TestResult object is passed a new one will be created.
 483      *
 484      * @param  PHPUnit_Framework_TestResult $result
 485      * @return PHPUnit_Framework_TestResult
 486      * @throws InvalidArgumentException
 487      */
 488     public function run(PHPUnit_Framework_TestResult $result = NULL)
 489     {
 490         if ($result === NULL) {
 491             $result = $this->createResult();
 492         }
 493
 494         $this->result = $result;
 495
 496         $this->setExpectedExceptionFromAnnotation();
 497         $this->setUseErrorHandlerFromAnnotation();
 498         $this->setUseOutputBufferingFromAnnotation();
 499
 500         if ($this->useErrorHandler !== NULL) {
 501             $oldErrorHandlerSetting = $result->getConvertErrorsToExceptions();
 502             $result->convertErrorsToExceptions($this->useErrorHandler);
 503         }
 504
 505         if (!$this->handleDependencies()) {
 506             return;
 507         }
 508
 509         if ($this->runTestInSeparateProcess === TRUE &&
 510             $this->inIsolation !== TRUE &&
 511             !$this instanceof PHPUnit_Extensions_SeleniumTestCase &&
 512             !$this instanceof PHPUnit_Extensions_PhptTestCase) {
 513             $class = new ReflectionClass($this);
 514
 515             $template = new Text_Template(
 516               sprintf(
 517                 '%s%sProcess%sTestCaseMethod.tpl',
 518
 519                 dirname(__FILE__),
 520                 DIRECTORY_SEPARATOR,
 521                 DIRECTORY_SEPARATOR,
 522                 DIRECTORY_SEPARATOR
 523               )
 524             );
 525
 526             if ($this->preserveGlobalState) {
 527                 $constants     = PHPUnit_Util_GlobalState::getConstantsAsString();
 528                 $globals       = PHPUnit_Util_GlobalState::getGlobalsAsString();
 529                 $includedFiles = PHPUnit_Util_GlobalState::getIncludedFilesAsString();
 530             } else {
 531                 $constants     = '';
 532                 $globals       = '';
 533                 $includedFiles = '';
 534             }
 535
 536             if ($result->getCollectCodeCoverageInformation()) {
 537                 $coverage = 'TRUE';
 538             } else {
 539                 $coverage = 'FALSE';
 540             }
 541
 542             if ($result->isStrict()) {
 543                 $strict = 'TRUE';
 544             } else {
 545                 $strict = 'FALSE';
 546             }
 547
 548             $data            = addcslashes(serialize($this->data), "'");
 549             $dependencyInput = addcslashes(
 550               serialize($this->dependencyInput), "'"
 551             );
 552             $includePath     = addslashes(get_include_path());
 553
 554             $template->setVar(
 555               array(
 556                 'filename'                       => $class->getFileName(),
 557                 'className'                      => $class->getName(),
 558                 'methodName'                     => $this->name,
 559                 'collectCodeCoverageInformation' => $coverage,
 560                 'data'                           => $data,
 561                 'dataName'                       => $this->dataName,
 562                 'dependencyInput'                => $dependencyInput,
 563                 'constants'                      => $constants,
 564                 'globals'                        => $globals,
 565                 'include_path'                   => $includePath,
 566                 'included_files'                 => $includedFiles,
 567                 'strict'                         => $strict
 568               )
 569             );
 570
 571             $this->prepareTemplate($template);
 572
 573             $php = PHPUnit_Util_PHP::factory();
 574             $php->runJob($template->render(), $this, $result);
 575         } else {
 576             $result->run($this);
 577         }
 578
 579         if ($this->useErrorHandler !== NULL) {
 580             $result->convertErrorsToExceptions($oldErrorHandlerSetting);
 581         }
 582
 583         $this->result = NULL;
 584
 585         return $result;
 586     }
 587
 588     /**
 589      * Runs the bare test sequence.
 590      */
 591     public function runBare()
 592     {
 593         $this->numAssertions = 0;
 594
 595         // Backup the $GLOBALS array and static attributes.
 596         if ($this->runTestInSeparateProcess !== TRUE &&
 597             $this->inIsolation !== TRUE) {
 598             if ($this->backupGlobals === NULL ||
 599                 $this->backupGlobals === TRUE) {
 600                 PHPUnit_Util_GlobalState::backupGlobals(
 601                   $this->backupGlobalsBlacklist
 602                 );
 603             }
 604
 605             if (version_compare(PHP_VERSION, '5.3', '>') &&
 606                 $this->backupStaticAttributes === TRUE) {
 607                 PHPUnit_Util_GlobalState::backupStaticAttributes(
 608                   $this->backupStaticAttributesBlacklist
 609                 );
 610             }
 611         }
 612
 613         // Start output buffering.
 614         if ($this->useOutputBuffering === TRUE) {
 615             ob_start();
 616         }
 617
 618         // Clean up stat cache.
 619         clearstatcache();
 620
 621         try {
 622             if ($this->inIsolation) {
 623                 $this->setUpBeforeClass();
 624             }
 625
 626             $this->setUp();
 627             $this->assertPreConditions();
 628             $this->testResult = $this->runTest();
 629             $this->verifyMockObjects();
 630             $this->assertPostConditions();
 631             $this->status = PHPUnit_Runner_BaseTestRunner::STATUS_PASSED;
 632         }
 633
 634         catch (PHPUnit_Framework_IncompleteTest $e) {
 635             $this->status        = PHPUnit_Runner_BaseTestRunner::STATUS_INCOMPLETE;
 636             $this->statusMessage = $e->getMessage();
 637         }
 638
 639         catch (PHPUnit_Framework_SkippedTest $e) {
 640             $this->status        = PHPUnit_Runner_BaseTestRunner::STATUS_SKIPPED;
 641             $this->statusMessage = $e->getMessage();
 642         }
 643
 644         catch (PHPUnit_Framework_AssertionFailedError $e) {
 645             $this->status        = PHPUnit_Runner_BaseTestRunner::STATUS_FAILURE;
 646             $this->statusMessage = $e->getMessage();
 647         }
 648
 649         catch (Exception $e) {
 650             $this->status        = PHPUnit_Runner_BaseTestRunner::STATUS_ERROR;
 651             $this->statusMessage = $e->getMessage();
 652         }
 653
 654         // Tear down the fixture. An exception raised in tearDown() will be
 655         // caught and passed on when no exception was raised before.
 656         try {
 657             $this->tearDown();
 658
 659             if ($this->inIsolation) {
 660                 $this->tearDownAfterClass();
 661             }
 662         }
 663
 664         catch (Exception $_e) {
 665             if (!isset($e)) {
 666                 $e = $_e;
 667             }
 668         }
 669
 670         // Stop output buffering.
 671         if ($this->useOutputBuffering === TRUE) {
 672             ob_end_clean();
 673         }
 674
 675         // Clean up stat cache.
 676         clearstatcache();
 677
 678         // Restore the $GLOBALS array and static attributes.
 679         if ($this->runTestInSeparateProcess !== TRUE &&
 680             $this->inIsolation !== TRUE) {
 681             if ($this->backupGlobals === NULL ||
 682                 $this->backupGlobals === TRUE) {
 683                 PHPUnit_Util_GlobalState::restoreGlobals(
 684                    $this->backupGlobalsBlacklist
 685                 );
 686             }
 687
 688             if (version_compare(PHP_VERSION, '5.3', '>') &&
 689                 $this->backupStaticAttributes === TRUE) {
 690                 PHPUnit_Util_GlobalState::restoreStaticAttributes();
 691             }
 692         }
 693
 694         // Clean up INI settings.
 695         foreach ($this->iniSettings as $varName => $oldValue) {
 696             ini_set($varName, $oldValue);
 697         }
 698
 699         $this->iniSettings = array();
 700
 701         // Clean up locale settings.
 702         foreach ($this->locale as $category => $locale) {
 703             setlocale($category, $locale);
 704         }
 705
 706         // Workaround for missing "finally".
 707         if (isset($e)) {
 708             $this->onNotSuccessfulTest($e);
 709         }
 710     }
 711
 712     /**
 713      * Override to run the test and assert its state.
 714      *
 715      * @return mixed
 716      * @throws RuntimeException
 717      */
 718     protected function runTest()
 719     {
 720         if ($this->name === NULL) {
 721             throw new PHPUnit_Framework_Exception(
 722               'PHPUnit_Framework_TestCase::$name must not be NULL.'
 723             );
 724         }
 725
 726         try {
 727             $class  = new ReflectionClass($this);
 728             $method = $class->getMethod($this->name);
 729         }
 730
 731         catch (ReflectionException $e) {
 732             $this->fail($e->getMessage());
 733         }
 734
 735         try {
 736             $testResult = $method->invokeArgs(
 737               $this, array_merge($this->data, $this->dependencyInput)
 738             );
 739         }
 740
 741         catch (Exception $e) {
 742             if (!$e instanceof PHPUnit_Framework_IncompleteTest &&
 743                 !$e instanceof PHPUnit_Framework_SkippedTest &&
 744                 is_string($this->expectedException) &&
 745                 $e instanceof $this->expectedException) {
 746                 if (is_string($this->expectedExceptionMessage) &&
 747                     !empty($this->expectedExceptionMessage)) {
 748                     $this->assertContains(
 749                       $this->expectedExceptionMessage,
 750                       $e->getMessage()
 751                     );
 752                 }
 753
 754                 if (is_int($this->expectedExceptionCode) &&
 755                     $this->expectedExceptionCode !== 0) {
 756                     $this->assertEquals(
 757                       $this->expectedExceptionCode, $e->getCode()
 758                     );
 759                 }
 760
 761                 $this->numAssertions++;
 762
 763                 return;
 764             } else {
 765                 throw $e;
 766             }
 767         }
 768
 769         if ($this->expectedException !== NULL) {
 770             $this->numAssertions++;
 771
 772             $this->syntheticFail(
 773               'Expected exception ' . $this->expectedException,
 774               '',
 775               0,
 776               $this->expectedExceptionTrace
 777             );
 778         }
 779
 780         return $testResult;
 781     }
 782
 783     /**
 784      * Verifies the mock object expectations.
 785      *
 786      * @since Method available since Release 3.5.0
 787      */
 788     protected function verifyMockObjects()
 789     {
 790         foreach ($this->mockObjects as $mockObject) {
 791             $this->numAssertions++;
 792             $mockObject->__phpunit_verify();
 793             $mockObject->__phpunit_cleanup();
 794         }
 795
 796         $this->mockObjects = array();
 797     }
 798
 799     /**
 800      * Sets the name of a TestCase.
 801      *
 802      * @param  string
 803      */
 804     public function setName($name)
 805     {
 806         $this->name = $name;
 807     }
 808
 809     /**
 810      * Sets the dependencies of a TestCase.
 811      *
 812      * @param  array $dependencies
 813      * @since  Method available since Release 3.4.0
 814      */
 815     public function setDependencies(array $dependencies)
 816     {
 817         $this->dependencies = $dependencies;
 818     }
 819
 820     /**
 821      * Sets
 822      *
 823      * @param  array $dependencyInput
 824      * @since  Method available since Release 3.4.0
 825      */
 826     public function setDependencyInput(array $dependencyInput)
 827     {
 828         $this->dependencyInput = $dependencyInput;
 829     }
 830
 831     /**
 832      * Calling this method in setUp() has no effect!
 833      *
 834      * @param  boolean $backupGlobals
 835      * @since  Method available since Release 3.3.0
 836      */
 837     public function setBackupGlobals($backupGlobals)
 838     {
 839         if (is_null($this->backupGlobals) && is_bool($backupGlobals)) {
 840             $this->backupGlobals = $backupGlobals;
 841         }
 842     }
 843
 844     /**
 845      * Calling this method in setUp() has no effect!
 846      *
 847      * @param  boolean $backupStaticAttributes
 848      * @since  Method available since Release 3.4.0
 849      */
 850     public function setBackupStaticAttributes($backupStaticAttributes)
 851     {
 852         if (is_null($this->backupStaticAttributes) &&
 853             is_bool($backupStaticAttributes)) {
 854             $this->backupStaticAttributes = $backupStaticAttributes;
 855         }
 856     }
 857
 858     /**
 859      * @param  boolean $runTestInSeparateProcess
 860      * @throws InvalidArgumentException
 861      * @since  Method available since Release 3.4.0
 862      */
 863     public function setRunTestInSeparateProcess($runTestInSeparateProcess)
 864     {
 865         if (is_bool($runTestInSeparateProcess)) {
 866             if ($this->runTestInSeparateProcess === NULL) {
 867                 $this->runTestInSeparateProcess = $runTestInSeparateProcess;
 868             }
 869         } else {
 870             throw PHPUnit_Util_InvalidArgumentHelper::factory(1, 'boolean');
 871         }
 872     }
 873
 874     /**
 875      * @param  boolean $preserveGlobalState
 876      * @throws InvalidArgumentException
 877      * @since  Method available since Release 3.4.0
 878      */
 879     public function setPreserveGlobalState($preserveGlobalState)
 880     {
 881         if (is_bool($preserveGlobalState)) {
 882             $this->preserveGlobalState = $preserveGlobalState;
 883         } else {
 884             throw PHPUnit_Util_InvalidArgumentHelper::factory(1, 'boolean');
 885         }
 886     }
 887
 888     /**
 889      * @param  boolean $inIsolation
 890      * @throws InvalidArgumentException
 891      * @since  Method available since Release 3.4.0
 892      */
 893     public function setInIsolation($inIsolation)
 894     {
 895         if (is_bool($inIsolation)) {
 896             $this->inIsolation = $inIsolation;
 897         } else {
 898             throw PHPUnit_Util_InvalidArgumentHelper::factory(1, 'boolean');
 899         }
 900     }
 901
 902     /**
 903      * @return mixed
 904      * @since  Method available since Release 3.4.0
 905      */
 906     public function getResult()
 907     {
 908         return $this->testResult;
 909     }
 910
 911     /**
 912      * @param  mixed $result
 913      * @since  Method available since Release 3.4.0
 914      */
 915     public function setResult($result)
 916     {
 917         $this->testResult = $result;
 918     }
 919
 920     /**
 921      * @return PHPUnit_Framework_TestResult
 922      * @since  Method available since Release 3.5.7
 923      */
 924     public function getTestResultObject()
 925     {
 926         return $this->result;
 927     }
 928
 929     /**
 930      * This method is a wrapper for the ini_set() function that automatically
 931      * resets the modified php.ini setting to its original value after the
 932      * test is run.
 933      *
 934      * @param  string  $varName
 935      * @param  string  $newValue
 936      * @throws InvalidArgumentException
 937      * @throws RuntimeException
 938      * @since  Method available since Release 3.0.0
 939      */
 940     protected function iniSet($varName, $newValue)
 941     {
 942         if (!is_string($varName)) {
 943             throw PHPUnit_Util_InvalidArgumentHelper::factory(1, 'string');
 944         }
 945
 946         $currentValue = ini_set($varName, $newValue);
 947
 948         if ($currentValue !== FALSE) {
 949             $this->iniSettings[$varName] = $currentValue;
 950         } else {
 951             throw new PHPUnit_Framework_Exception(
 952               sprintf(
 953                 'INI setting "%s" could not be set to "%s".',
 954                 $varName,
 955                 $newValue
 956               )
 957             );
 958         }
 959     }
 960
 961     /**
 962      * This method is a wrapper for the setlocale() function that automatically
 963      * resets the locale to its original value after the test is run.
 964      *
 965      * @param  integer $category
 966      * @param  string  $locale
 967      * @throws InvalidArgumentException
 968      * @throws RuntimeException
 969      * @since  Method available since Release 3.1.0
 970      */
 971     protected function setLocale()
 972     {
 973         $args = func_get_args();
 974
 975         if (count($args) < 2) {
 976             throw new InvalidArgumentException;
 977         }
 978
 979         $category = $args[0];
 980         $locale   = $args[1];
 981
 982         $categories = array(
 983           LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME
 984         );
 985
 986         if (defined('LC_MESSAGES')) {
 987             $categories[] = LC_MESSAGES;
 988         }
 989
 990         if (!in_array($category, $categories)) {
 991             throw new InvalidArgumentException;
 992         }
 993
 994         if (!is_array($locale) && !is_string($locale)) {
 995             throw new InvalidArgumentException;
 996         }
 997
 998         $this->locale[$category] = setlocale($category, NULL);
 999
1000         $result = call_user_func_array( 'setlocale', $args );
1001
1002         if ($result === FALSE) {
1003             throw new PHPUnit_Framework_Exception(
1004               'The locale functionality is not implemented on your platform, ' .
1005               'the specified locale does not exist or the category name is ' .
1006               'invalid.'
1007             );
1008         }
1009     }
1010
1011     /**
1012      * Returns a mock object for the specified class.
1013      *
1014      * @param  string  $originalClassName
1015      * @param  array   $methods
1016      * @param  array   $arguments
1017      * @param  string  $mockClassName
1018      * @param  boolean $callOriginalConstructor
1019      * @param  boolean $callOriginalClone
1020      * @param  boolean $callAutoload
1021      * @return PHPUnit_Framework_MockObject_MockObject
1022      * @throws InvalidArgumentException
1023      * @since  Method available since Release 3.0.0
1024      */
1025     public function getMock($originalClassName, $methods = array(), array $arguments = array(), $mockClassName = '', $callOriginalConstructor = TRUE, $callOriginalClone = TRUE, $callAutoload = TRUE)
1026     {
1027         $mockObject = PHPUnit_Framework_MockObject_Generator::getMock(
1028           $originalClassName,
1029           $methods,
1030           $arguments,
1031           $mockClassName,
1032           $callOriginalConstructor,
1033           $callOriginalClone,
1034           $callAutoload
1035         );
1036
1037         $this->mockObjects[] = $mockObject;
1038
1039         return $mockObject;
1040     }
1041
1042     /**
1043      * Returns a builder object to create mock objects using a fluent interface.
1044      *
1045      * @param  string $className
1046      * @return PHPUnit_Framework_MockObject_MockBuilder
1047      * @since  Method available since Release 3.5.0
1048      */
1049     public function getMockBuilder($className)
1050     {
1051         return new PHPUnit_Framework_MockObject_MockBuilder(
1052           $this, $className
1053         );
1054     }
1055
1056     /**
1057      * Mocks the specified class and returns the name of the mocked class.
1058      *
1059      * @param  string  $originalClassName
1060      * @param  array   $methods
1061      * @param  array   $arguments
1062      * @param  string  $mockClassName
1063      * @param  boolean $callOriginalConstructor
1064      * @param  boolean $callOriginalClone
1065      * @param  boolean $callAutoload
1066      * @return string
1067      * @throws InvalidArgumentException
1068      * @since  Method available since Release 3.5.0
1069      */
1070     protected function getMockClass($originalClassName, $methods = array(), array $arguments = array(), $mockClassName = '', $callOriginalConstructor = FALSE, $callOriginalClone = TRUE, $callAutoload = TRUE)
1071     {
1072         $mock = $this->getMock(
1073           $originalClassName,
1074           $methods,
1075           $arguments,
1076           $mockClassName,
1077           $callOriginalConstructor,
1078           $callOriginalClone,
1079           $callAutoload
1080         );
1081
1082         return get_class($mock);
1083     }
1084
1085     /**
1086      * Returns a mock object for the specified abstract class with all abstract
1087      * methods of the class mocked. Concrete methods are not mocked.
1088      *
1089      * @param  string  $originalClassName
1090      * @param  array   $arguments
1091      * @param  string  $mockClassName
1092      * @param  boolean $callOriginalConstructor
1093      * @param  boolean $callOriginalClone
1094      * @param  boolean $callAutoload
1095      * @return PHPUnit_Framework_MockObject_MockObject
1096      * @since  Method available since Release 3.4.0
1097      * @throws InvalidArgumentException
1098      */
1099     public function getMockForAbstractClass($originalClassName, array $arguments = array(), $mockClassName = '', $callOriginalConstructor = TRUE, $callOriginalClone = TRUE, $callAutoload = TRUE)
1100     {
1101         $mockObject = PHPUnit_Framework_MockObject_Generator::getMockForAbstractClass(
1102           $originalClassName,
1103           $arguments,
1104           $mockClassName,
1105           $callOriginalConstructor,
1106           $callOriginalClone,
1107           $callAutoload
1108         );
1109
1110         $this->mockObjects[] = $mockObject;
1111
1112         return $mockObject;
1113     }
1114
1115     /**
1116      * Returns a mock object based on the given WSDL file.
1117      *
1118      * @param  string  $wsdlFile
1119      * @param  string  $originalClassName
1120      * @param  string  $mockClassName
1121      * @param  array   $methods
1122      * @param  boolean $callOriginalConstructor
1123      * @return PHPUnit_Framework_MockObject_MockObject
1124      * @since  Method available since Release 3.4.0
1125      */
1126     protected function getMockFromWsdl($wsdlFile, $originalClassName = '', $mockClassName = '', array $methods = array(), $callOriginalConstructor = TRUE)
1127     {
1128         if ($originalClassName === '') {
1129             $originalClassName = str_replace(
1130               '.wsdl', '', basename($wsdlFile)
1131             );
1132         }
1133
1134         eval(
1135           PHPUnit_Framework_MockObject_Generator::generateClassFromWsdl(
1136             $wsdlFile, $originalClassName, $methods
1137           )
1138         );
1139
1140         return $this->getMock(
1141           $originalClassName,
1142           $methods,
1143           array('', array()),
1144           $mockClassName,
1145           $callOriginalConstructor,
1146           FALSE,
1147           FALSE
1148         );
1149     }
1150
1151     /**
1152      * Adds a value to the assertion counter.
1153      *
1154      * @param integer $count
1155      * @since Method available since Release 3.3.3
1156      */
1157     public function addToAssertionCount($count)
1158     {
1159         $this->numAssertions += $count;
1160     }
1161
1162     /**
1163      * Returns the number of assertions performed by this test.
1164      *
1165      * @return integer
1166      * @since  Method available since Release 3.3.0
1167      */
1168     public function getNumAssertions()
1169     {
1170         return $this->numAssertions;
1171     }
1172
1173     /**
1174      * Returns a matcher that matches when the method it is evaluated for
1175      * is executed zero or more times.
1176      *
1177      * @return PHPUnit_Framework_MockObject_Matcher_AnyInvokedCount
1178      * @since  Method available since Release 3.0.0
1179      */
1180     public static function any()
1181     {
1182         return new PHPUnit_Framework_MockObject_Matcher_AnyInvokedCount;
1183     }
1184
1185     /**
1186      * Returns a matcher that matches when the method it is evaluated for
1187      * is never executed.
1188      *
1189      * @return PHPUnit_Framework_MockObject_Matcher_InvokedCount
1190      * @since  Method available since Release 3.0.0
1191      */
1192     public static function never()
1193     {
1194         return new PHPUnit_Framework_MockObject_Matcher_InvokedCount(0);
1195     }
1196
1197     /**
1198      * Returns a matcher that matches when the method it is evaluated for
1199      * is executed at least once.
1200      *
1201      * @return PHPUnit_Framework_MockObject_Matcher_InvokedAtLeastOnce
1202      * @since  Method available since Release 3.0.0
1203      */
1204     public static function atLeastOnce()
1205     {
1206         return new PHPUnit_Framework_MockObject_Matcher_InvokedAtLeastOnce;
1207     }
1208
1209     /**
1210      * Returns a matcher that matches when the method it is evaluated for
1211      * is executed exactly once.
1212      *
1213      * @return PHPUnit_Framework_MockObject_Matcher_InvokedCount
1214      * @since  Method available since Release 3.0.0
1215      */
1216     public static function once()
1217     {
1218         return new PHPUnit_Framework_MockObject_Matcher_InvokedCount(1);
1219     }
1220
1221     /**
1222      * Returns a matcher that matches when the method it is evaluated for
1223      * is executed exactly $count times.
1224      *
1225      * @param  integer $count
1226      * @return PHPUnit_Framework_MockObject_Matcher_InvokedCount
1227      * @since  Method available since Release 3.0.0
1228      */
1229     public static function exactly($count)
1230     {
1231         return new PHPUnit_Framework_MockObject_Matcher_InvokedCount($count);
1232     }
1233
1234     /**
1235      * Returns a matcher that matches when the method it is evaluated for
1236      * is invoked at the given $index.
1237      *
1238      * @param  integer $index
1239      * @return PHPUnit_Framework_MockObject_Matcher_InvokedAtIndex
1240      * @since  Method available since Release 3.0.0
1241      */
1242     public static function at($index)
1243     {
1244         return new PHPUnit_Framework_MockObject_Matcher_InvokedAtIndex($index);
1245     }
1246
1247     /**
1248      *
1249      *
1250      * @param  mixed $value
1251      * @return PHPUnit_Framework_MockObject_Stub_Return
1252      * @since  Method available since Release 3.0.0
1253      */
1254     public static function returnValue($value)
1255     {
1256         return new PHPUnit_Framework_MockObject_Stub_Return($value);
1257     }
1258
1259     /**
1260      *
1261      *
1262      * @param  integer $argumentIndex
1263      * @return PHPUnit_Framework_MockObject_Stub_ReturnArgument
1264      * @since  Method available since Release 3.3.0
1265      */
1266     public static function returnArgument($argumentIndex)
1267     {
1268         return new PHPUnit_Framework_MockObject_Stub_ReturnArgument(
1269           $argumentIndex
1270         );
1271     }
1272
1273     /**
1274      *
1275      *
1276      * @param  mixed $callback
1277      * @return PHPUnit_Framework_MockObject_Stub_ReturnCallback
1278      * @since  Method available since Release 3.3.0
1279      */
1280     public static function returnCallback($callback)
1281     {
1282         return new PHPUnit_Framework_MockObject_Stub_ReturnCallback($callback);
1283     }
1284
1285     /**
1286      *
1287      *
1288      * @param  Exception $exception
1289      * @return PHPUnit_Framework_MockObject_Stub_Exception
1290      * @since  Method available since Release 3.1.0
1291      */
1292     public static function throwException(Exception $exception)
1293     {
1294         return new PHPUnit_Framework_MockObject_Stub_Exception($exception);
1295     }
1296
1297     /**
1298      *
1299      *
1300      * @param  mixed $value, ...
1301      * @return PHPUnit_Framework_MockObject_Stub_ConsecutiveCalls
1302      * @since  Method available since Release 3.0.0
1303      */
1304     public static function onConsecutiveCalls()
1305     {
1306         $args = func_get_args();
1307
1308         return new PHPUnit_Framework_MockObject_Stub_ConsecutiveCalls($args);
1309     }
1310
1311     /**
1312      * @param  mixed $data
1313      * @return string
1314      * @since  Method available since Release 3.2.1
1315      */
1316     protected function dataToString($data)
1317     {
1318         $result = array();
1319
1320         foreach ($data as $_data) {
1321             if (is_array($_data)) {
1322                 $result[] = 'array(' . $this->dataToString($_data) . ')';
1323             }
1324
1325             else if (is_object($_data)) {
1326                 $object = new ReflectionObject($_data);
1327
1328                 if ($object->hasMethod('__toString')) {
1329                     $result[] = (string)$_data;
1330                 } else {
1331                     $result[] = get_class($_data);
1332                 }
1333             }
1334
1335             else if (is_resource($_data)) {
1336                 $result[] = '<resource>';
1337             }
1338
1339             else {
1340                 $result[] = var_export($_data, TRUE);
1341             }
1342         }
1343
1344         return join(', ', $result);
1345     }
1346
1347     /**
1348      * Gets the data set description of a TestCase.
1349      *
1350      * @param  boolean $includeData
1351      * @return string
1352      * @since  Method available since Release 3.3.0
1353      */
1354     protected function getDataSetAsString($includeData = TRUE)
1355     {
1356         $buffer = '';
1357
1358         if (!empty($this->data)) {
1359             if (is_int($this->dataName)) {
1360                 $buffer .= sprintf(' with data set #%d', $this->dataName);
1361             } else {
1362                 $buffer .= sprintf(' with data set "%s"', $this->dataName);
1363             }
1364
1365             if ($includeData) {
1366                 $buffer .= sprintf(' (%s)', $this->dataToString($this->data));
1367             }
1368         }
1369
1370         return $buffer;
1371     }
1372
1373     /**
1374      * Creates a default TestResult object.
1375      *
1376      * @return PHPUnit_Framework_TestResult
1377      */
1378     protected function createResult()
1379     {
1380         return new PHPUnit_Framework_TestResult;
1381     }
1382
1383     /**
1384      * @since Method available since Release 3.5.4
1385      */
1386     protected function handleDependencies()
1387     {
1388         if (!empty($this->dependencies) && !$this->inIsolation) {
1389             $className  = get_class($this);
1390             $passed     = $this->result->passed();
1391             $passedKeys = array_keys($passed);
1392             $numKeys    = count($passedKeys);
1393
1394             for ($i = 0; $i < $numKeys; $i++) {
1395                 $pos = strpos($passedKeys[$i], ' with data set');
1396
1397                 if ($pos !== FALSE) {
1398                     $passedKeys[$i] = substr($passedKeys[$i], 0, $pos);
1399                 }
1400             }
1401
1402             $passedKeys = array_flip(array_unique($passedKeys));
1403
1404             foreach ($this->dependencies as $dependency) {
1405                 if (strpos($dependency, '::') === FALSE) {
1406                     $dependency = $className . '::' . $dependency;
1407                 }
1408
1409                 if (!isset($passedKeys[$dependency])) {
1410                     $this->result->addError(
1411                       $this,
1412                       new PHPUnit_Framework_SkippedTestError(
1413                         sprintf(
1414                           'This test depends on "%s" to pass.', $dependency
1415                         )
1416                       ),
1417                       0
1418                     );
1419
1420                     return FALSE;
1421                 } else {
1422                     if (isset($passed[$dependency])) {
1423                         $this->dependencyInput[] = $passed[$dependency];
1424                     } else {
1425                         $this->dependencyInput[] = NULL;
1426                     }
1427                 }
1428             }
1429         }
1430
1431         return TRUE;
1432     }
1433
1434     /**
1435      * This method is called before the first test of this test class is run.
1436      *
1437      * @since Method available since Release 3.4.0
1438      */
1439     public static function setUpBeforeClass()
1440     {
1441     }
1442
1443     /**
1444      * Sets up the fixture, for example, open a network connection.
1445      * This method is called before a test is executed.
1446      *
1447      */
1448     protected function setUp()
1449     {
1450     }
1451
1452     /**
1453      * Performs assertions shared by all tests of a test case.
1454      *
1455      * This method is called before the execution of a test starts
1456      * and after setUp() is called.
1457      *
1458      * @since  Method available since Release 3.2.8
1459      */
1460     protected function assertPreConditions()
1461     {
1462     }
1463
1464     /**
1465      * Performs assertions shared by all tests of a test case.
1466      *
1467      * This method is called before the execution of a test ends
1468      * and before tearDown() is called.
1469      *
1470      * @since  Method available since Release 3.2.8
1471      */
1472     protected function assertPostConditions()
1473     {
1474     }
1475
1476     /**
1477      * Tears down the fixture, for example, close a network connection.
1478      * This method is called after a test is executed.
1479      */
1480     protected function tearDown()
1481     {
1482     }
1483
1484     /**
1485      * This method is called after the last test of this test class is run.
1486      *
1487      * @since Method available since Release 3.4.0
1488      */
1489     public static function tearDownAfterClass()
1490     {
1491     }
1492
1493     /**
1494      * This method is called when a test method did not execute successfully.
1495      *
1496      * @param Exception $e
1497      * @since Method available since Release 3.4.0
1498      */
1499     protected function onNotSuccessfulTest(Exception $e)
1500     {
1501         throw $e;
1502     }
1503
1504     /**
1505      * Performs custom preparations on the process isolation template.
1506      *
1507      * @param Text_Template $template
1508      * @since Method available since Release 3.4.0
1509      */
1510     protected function prepareTemplate(Text_Template $template)
1511     {
1512     }
1513 }