3 * This file is part of PHPUnit.
5 * (c) Sebastian Bergmann <sebastian@phpunit.de>
7 * For the full copyright and license information, please view the LICENSE
8 * file that was distributed with this source code.
12 * A TestSuite is a composite of Tests. It runs a collection of test cases.
14 * @since Class available since Release 2.0.0
16 class PHPUnit_Framework_TestSuite implements PHPUnit_Framework_Test, PHPUnit_Framework_SelfDescribing, IteratorAggregate
19 * Last count of tests in this suite.
23 private $cachedNumTests;
26 * Enable or disable the backup and restoration of the $GLOBALS array.
30 protected $backupGlobals = null;
33 * Enable or disable the backup and restoration of static attributes.
37 protected $backupStaticAttributes = null;
42 private $disallowChangesToGlobalState = null;
47 protected $runTestInSeparateProcess = false;
50 * The name of the test suite.
57 * The test groups of the test suite.
61 protected $groups = array();
64 * The tests in the test suite.
68 protected $tests = array();
71 * The number of tests in the test suite.
75 protected $numTests = -1;
80 protected $testCase = false;
85 protected $foundClasses = array();
88 * @var PHPUnit_Runner_Filter_Factory
90 private $iteratorFilter = null;
93 * Constructs a new TestSuite:
95 * - PHPUnit_Framework_TestSuite() constructs an empty TestSuite.
97 * - PHPUnit_Framework_TestSuite(ReflectionClass) constructs a
98 * TestSuite from the given class.
100 * - PHPUnit_Framework_TestSuite(ReflectionClass, String)
101 * constructs a TestSuite from the given class with the given
104 * - PHPUnit_Framework_TestSuite(String) either constructs a
105 * TestSuite from the given class (if the passed string is the
106 * name of an existing class) or constructs an empty TestSuite
107 * with the given name.
109 * @param mixed $theClass
110 * @param string $name
112 * @throws PHPUnit_Framework_Exception
114 public function __construct($theClass = '', $name = '')
116 $argumentsValid = false;
118 if (is_object($theClass) &&
119 $theClass instanceof ReflectionClass) {
120 $argumentsValid = true;
121 } elseif (is_string($theClass) &&
123 class_exists($theClass, false)) {
124 $argumentsValid = true;
130 $theClass = new ReflectionClass($theClass);
131 } elseif (is_string($theClass)) {
132 $this->setName($theClass);
137 if (!$argumentsValid) {
138 throw new PHPUnit_Framework_Exception;
141 if (!$theClass->isSubclassOf('PHPUnit_Framework_TestCase')) {
142 throw new PHPUnit_Framework_Exception(
143 'Class "' . $theClass->name . '" does not extend PHPUnit_Framework_TestCase.'
148 $this->setName($name);
150 $this->setName($theClass->getName());
153 $constructor = $theClass->getConstructor();
155 if ($constructor !== null &&
156 !$constructor->isPublic()) {
160 'Class "%s" has no public constructor.',
169 foreach ($theClass->getMethods() as $method) {
170 $this->addTestMethod($theClass, $method);
173 if (empty($this->tests)) {
177 'No tests found in class "%s".',
184 $this->testCase = true;
188 * Returns a string representation of the test suite.
192 public function toString()
194 return $this->getName();
198 * Adds a test to the suite.
200 * @param PHPUnit_Framework_Test $test
201 * @param array $groups
203 public function addTest(PHPUnit_Framework_Test $test, $groups = array())
205 $class = new ReflectionClass($test);
207 if (!$class->isAbstract()) {
208 $this->tests[] = $test;
209 $this->numTests = -1;
211 if ($test instanceof self &&
213 $groups = $test->getGroups();
216 if (empty($groups)) {
217 $groups = array('default');
220 foreach ($groups as $group) {
221 if (!isset($this->groups[$group])) {
222 $this->groups[$group] = array($test);
224 $this->groups[$group][] = $test;
231 * Adds the tests from the given class to the suite.
233 * @param mixed $testClass
235 * @throws PHPUnit_Framework_Exception
237 public function addTestSuite($testClass)
239 if (is_string($testClass) && class_exists($testClass)) {
240 $testClass = new ReflectionClass($testClass);
243 if (!is_object($testClass)) {
244 throw PHPUnit_Util_InvalidArgumentHelper::factory(
246 'class name or object'
250 if ($testClass instanceof self) {
251 $this->addTest($testClass);
252 } elseif ($testClass instanceof ReflectionClass) {
253 $suiteMethod = false;
255 if (!$testClass->isAbstract()) {
256 if ($testClass->hasMethod(PHPUnit_Runner_BaseTestRunner::SUITE_METHODNAME)) {
257 $method = $testClass->getMethod(
258 PHPUnit_Runner_BaseTestRunner::SUITE_METHODNAME
261 if ($method->isStatic()) {
263 $method->invoke(null, $testClass->getName())
271 if (!$suiteMethod && !$testClass->isAbstract()) {
272 $this->addTest(new self($testClass));
275 throw new PHPUnit_Framework_Exception;
280 * Wraps both <code>addTest()</code> and <code>addTestSuite</code>
281 * as well as the separate import statements for the user's convenience.
283 * If the named file cannot be read or there are no new tests that can be
284 * added, a <code>PHPUnit_Framework_Warning</code> will be created instead,
285 * leaving the current test run untouched.
287 * @param string $filename
289 * @throws PHPUnit_Framework_Exception
291 * @since Method available since Release 2.3.0
293 public function addTestFile($filename)
295 if (!is_string($filename)) {
296 throw PHPUnit_Util_InvalidArgumentHelper::factory(1, 'string');
299 if (file_exists($filename) && substr($filename, -5) == '.phpt') {
301 new PHPUnit_Extensions_PhptTestCase($filename)
307 // The given file may contain further stub classes in addition to the
308 // test class itself. Figure out the actual test class.
309 $classes = get_declared_classes();
310 $filename = PHPUnit_Util_Fileloader::checkAndLoad($filename);
311 $newClasses = array_diff(get_declared_classes(), $classes);
313 // The diff is empty in case a parent class (with test methods) is added
314 // AFTER a child class that inherited from it. To account for that case,
315 // cumulate all discovered classes, so the parent class may be found in
316 // a later invocation.
318 // On the assumption that test classes are defined first in files,
319 // process discovered classes in approximate LIFO order, so as to
320 // avoid unnecessary reflection.
321 $this->foundClasses = array_merge($newClasses, $this->foundClasses);
324 // The test class's name must match the filename, either in full, or as
325 // a PEAR/PSR-0 prefixed shortname ('NameSpace_ShortName'), or as a
326 // PSR-1 local shortname ('NameSpace\ShortName'). The comparison must be
327 // anchored to prevent false-positive matches (e.g., 'OtherShortName').
328 $shortname = basename($filename, '.php');
329 $shortnameRegEx = '/(?:^|_|\\\\)' . preg_quote($shortname, '/') . '$/';
331 foreach ($this->foundClasses as $i => $className) {
332 if (preg_match($shortnameRegEx, $className)) {
333 $class = new ReflectionClass($className);
335 if ($class->getFileName() == $filename) {
336 $newClasses = array($className);
337 unset($this->foundClasses[$i]);
343 foreach ($newClasses as $className) {
344 $class = new ReflectionClass($className);
346 if (!$class->isAbstract()) {
347 if ($class->hasMethod(PHPUnit_Runner_BaseTestRunner::SUITE_METHODNAME)) {
348 $method = $class->getMethod(
349 PHPUnit_Runner_BaseTestRunner::SUITE_METHODNAME
352 if ($method->isStatic()) {
353 $this->addTest($method->invoke(null, $className));
355 } elseif ($class->implementsInterface('PHPUnit_Framework_Test')) {
356 $this->addTestSuite($class);
361 $this->numTests = -1;
365 * Wrapper for addTestFile() that adds multiple test files.
367 * @param array|Iterator $filenames
369 * @throws PHPUnit_Framework_Exception
371 * @since Method available since Release 2.3.0
373 public function addTestFiles($filenames)
375 if (!(is_array($filenames) ||
376 (is_object($filenames) && $filenames instanceof Iterator))) {
377 throw PHPUnit_Util_InvalidArgumentHelper::factory(
383 foreach ($filenames as $filename) {
384 $this->addTestFile((string) $filename);
389 * Counts the number of test cases that will be run by this test.
391 * @param bool $preferCache Indicates if cache is preferred.
395 public function count($preferCache = false)
397 if ($preferCache && $this->cachedNumTests != null) {
398 $numTests = $this->cachedNumTests;
401 foreach ($this as $test) {
402 $numTests += count($test);
404 $this->cachedNumTests = $numTests;
411 * @param ReflectionClass $theClass
412 * @param string $name
414 * @return PHPUnit_Framework_Test
416 * @throws PHPUnit_Framework_Exception
418 public static function createTest(ReflectionClass $theClass, $name)
420 $className = $theClass->getName();
422 if (!$theClass->isInstantiable()) {
423 return self::warning(
424 sprintf('Cannot instantiate class "%s".', $className)
428 $backupSettings = PHPUnit_Util_Test::getBackupSettings(
433 $preserveGlobalState = PHPUnit_Util_Test::getPreserveGlobalStateSettings(
438 $runTestInSeparateProcess = PHPUnit_Util_Test::getProcessIsolationSettings(
443 $constructor = $theClass->getConstructor();
445 if ($constructor !== null) {
446 $parameters = $constructor->getParameters();
448 // TestCase() or TestCase($name)
449 if (count($parameters) < 2) {
450 $test = new $className;
451 } // TestCase($name, $data)
454 $data = PHPUnit_Util_Test::getProvidedData(
458 } catch (PHPUnit_Framework_IncompleteTestError $e) {
460 'Test for %s::%s marked incomplete by data provider',
465 $_message = $e->getMessage();
467 if (!empty($_message)) {
468 $message .= "\n" . $_message;
471 $data = self::incompleteTest($className, $name, $message);
472 } catch (PHPUnit_Framework_SkippedTestError $e) {
474 'Test for %s::%s skipped by data provider',
479 $_message = $e->getMessage();
481 if (!empty($_message)) {
482 $message .= "\n" . $_message;
485 $data = self::skipTest($className, $name, $message);
486 } catch (Throwable $_t) {
488 } catch (Exception $_t) {
494 'The data provider specified for %s::%s is invalid.',
499 $_message = $t->getMessage();
501 if (!empty($_message)) {
502 $message .= "\n" . $_message;
505 $data = self::warning($message);
508 // Test method with @dataProvider.
510 $test = new PHPUnit_Framework_TestSuite_DataProvider(
511 $className . '::' . $name
515 $data = self::warning(
517 'No tests found in suite "%s".',
523 $groups = PHPUnit_Util_Test::getGroups($className, $name);
525 if ($data instanceof PHPUnit_Framework_Warning ||
526 $data instanceof PHPUnit_Framework_SkippedTestCase ||
527 $data instanceof PHPUnit_Framework_IncompleteTestCase) {
528 $test->addTest($data, $groups);
530 foreach ($data as $_dataName => $_data) {
531 $_test = new $className($name, $_data, $_dataName);
533 if ($runTestInSeparateProcess) {
534 $_test->setRunTestInSeparateProcess(true);
536 if ($preserveGlobalState !== null) {
537 $_test->setPreserveGlobalState($preserveGlobalState);
541 if ($backupSettings['backupGlobals'] !== null) {
542 $_test->setBackupGlobals(
543 $backupSettings['backupGlobals']
547 if ($backupSettings['backupStaticAttributes'] !== null) {
548 $_test->setBackupStaticAttributes(
549 $backupSettings['backupStaticAttributes']
553 $test->addTest($_test, $groups);
557 $test = new $className;
563 throw new PHPUnit_Framework_Exception('No valid test provided.');
566 if ($test instanceof PHPUnit_Framework_TestCase) {
567 $test->setName($name);
569 if ($runTestInSeparateProcess) {
570 $test->setRunTestInSeparateProcess(true);
572 if ($preserveGlobalState !== null) {
573 $test->setPreserveGlobalState($preserveGlobalState);
577 if ($backupSettings['backupGlobals'] !== null) {
578 $test->setBackupGlobals($backupSettings['backupGlobals']);
581 if ($backupSettings['backupStaticAttributes'] !== null) {
582 $test->setBackupStaticAttributes(
583 $backupSettings['backupStaticAttributes']
592 * Creates a default TestResult object.
594 * @return PHPUnit_Framework_TestResult
596 protected function createResult()
598 return new PHPUnit_Framework_TestResult;
602 * Returns the name of the suite.
606 public function getName()
612 * Returns the test groups of the suite.
616 * @since Method available since Release 3.2.0
618 public function getGroups()
620 return array_keys($this->groups);
623 public function getGroupDetails()
625 return $this->groups;
629 * Set tests groups of the test case
631 * @param array $groups
633 * @since Method available since Release 4.0.0
635 public function setGroupDetails(array $groups)
637 $this->groups = $groups;
641 * Runs the tests and collects their result in a TestResult.
643 * @param PHPUnit_Framework_TestResult $result
645 * @return PHPUnit_Framework_TestResult
647 public function run(PHPUnit_Framework_TestResult $result = null)
649 if ($result === null) {
650 $result = $this->createResult();
653 if (count($this) == 0) {
657 $hookMethods = PHPUnit_Util_Test::getHookMethods($this->name);
659 $result->startTestSuite($this);
664 foreach ($hookMethods['beforeClass'] as $beforeClassMethod) {
665 if ($this->testCase === true &&
666 class_exists($this->name, false) &&
667 method_exists($this->name, $beforeClassMethod)) {
668 if ($missingRequirements = PHPUnit_Util_Test::getMissingRequirements($this->name, $beforeClassMethod)) {
669 $this->markTestSuiteSkipped(implode(PHP_EOL, $missingRequirements));
672 call_user_func(array($this->name, $beforeClassMethod));
675 } catch (PHPUnit_Framework_SkippedTestSuiteError $e) {
676 $numTests = count($this);
678 for ($i = 0; $i < $numTests; $i++) {
679 $result->startTest($this);
680 $result->addFailure($this, $e, 0);
681 $result->endTest($this, 0);
685 $result->endTestSuite($this);
688 } catch (Throwable $_t) {
690 } catch (Exception $_t) {
695 $numTests = count($this);
697 for ($i = 0; $i < $numTests; $i++) {
698 $result->startTest($this);
699 $result->addError($this, $t, 0);
700 $result->endTest($this, 0);
704 $result->endTestSuite($this);
709 foreach ($this as $test) {
710 if ($result->shouldStop()) {
714 if ($test instanceof PHPUnit_Framework_TestCase ||
715 $test instanceof self) {
716 $test->setDisallowChangesToGlobalState($this->disallowChangesToGlobalState);
717 $test->setBackupGlobals($this->backupGlobals);
718 $test->setBackupStaticAttributes($this->backupStaticAttributes);
719 $test->setRunTestInSeparateProcess($this->runTestInSeparateProcess);
725 foreach ($hookMethods['afterClass'] as $afterClassMethod) {
726 if ($this->testCase === true && class_exists($this->name, false) && method_exists($this->name, $afterClassMethod)) {
727 call_user_func(array($this->name, $afterClassMethod));
733 $result->endTestSuite($this);
739 * @param bool $runTestInSeparateProcess
741 * @throws PHPUnit_Framework_Exception
743 * @since Method available since Release 3.7.0
745 public function setRunTestInSeparateProcess($runTestInSeparateProcess)
747 if (is_bool($runTestInSeparateProcess)) {
748 $this->runTestInSeparateProcess = $runTestInSeparateProcess;
750 throw PHPUnit_Util_InvalidArgumentHelper::factory(1, 'boolean');
759 * @param PHPUnit_Framework_Test $test
760 * @param PHPUnit_Framework_TestResult $result
762 public function runTest(PHPUnit_Framework_Test $test, PHPUnit_Framework_TestResult $result)
768 * Sets the name of the suite.
772 public function setName($name)
778 * Returns the test at the given index.
782 * @return PHPUnit_Framework_Test
784 public function testAt($index)
786 if (isset($this->tests[$index])) {
787 return $this->tests[$index];
794 * Returns the tests as an enumeration.
798 public function tests()
804 * Set tests of the test suite
806 * @param array $tests
808 * @since Method available since Release 4.0.0
810 public function setTests(array $tests)
812 $this->tests = $tests;
816 * Mark the test suite as skipped.
818 * @param string $message
820 * @throws PHPUnit_Framework_SkippedTestSuiteError
822 * @since Method available since Release 3.0.0
824 public function markTestSuiteSkipped($message = '')
826 throw new PHPUnit_Framework_SkippedTestSuiteError($message);
830 * @param ReflectionClass $class
831 * @param ReflectionMethod $method
833 protected function addTestMethod(ReflectionClass $class, ReflectionMethod $method)
835 if (!$this->isTestMethod($method)) {
839 $name = $method->getName();
841 if (!$method->isPublic()) {
845 'Test method "%s" in test class "%s" is not public.',
855 $test = self::createTest($class, $name);
857 if ($test instanceof PHPUnit_Framework_TestCase ||
858 $test instanceof PHPUnit_Framework_TestSuite_DataProvider) {
859 $test->setDependencies(
860 PHPUnit_Util_Test::getDependencies($class->getName(), $name)
866 PHPUnit_Util_Test::getGroups($class->getName(), $name)
871 * @param ReflectionMethod $method
875 public static function isTestMethod(ReflectionMethod $method)
877 if (strpos($method->name, 'test') === 0) {
881 // @scenario on TestCase::testMethod()
882 // @test on TestCase::testMethod()
883 $doc_comment = $method->getDocComment();
885 return strpos($doc_comment, '@test') !== false ||
886 strpos($doc_comment, '@scenario') !== false;
890 * @param string $message
892 * @return PHPUnit_Framework_Warning
894 protected static function warning($message)
896 return new PHPUnit_Framework_Warning($message);
900 * @param string $class
901 * @param string $methodName
902 * @param string $message
904 * @return PHPUnit_Framework_SkippedTestCase
906 * @since Method available since Release 4.3.0
908 protected static function skipTest($class, $methodName, $message)
910 return new PHPUnit_Framework_SkippedTestCase($class, $methodName, $message);
914 * @param string $class
915 * @param string $methodName
916 * @param string $message
918 * @return PHPUnit_Framework_IncompleteTestCase
920 * @since Method available since Release 4.3.0
922 protected static function incompleteTest($class, $methodName, $message)
924 return new PHPUnit_Framework_IncompleteTestCase($class, $methodName, $message);
928 * @param bool $disallowChangesToGlobalState
930 * @since Method available since Release 4.6.0
932 public function setDisallowChangesToGlobalState($disallowChangesToGlobalState)
934 if (is_null($this->disallowChangesToGlobalState) && is_bool($disallowChangesToGlobalState)) {
935 $this->disallowChangesToGlobalState = $disallowChangesToGlobalState;
940 * @param bool $backupGlobals
942 * @since Method available since Release 3.3.0
944 public function setBackupGlobals($backupGlobals)
946 if (is_null($this->backupGlobals) && is_bool($backupGlobals)) {
947 $this->backupGlobals = $backupGlobals;
952 * @param bool $backupStaticAttributes
954 * @since Method available since Release 3.4.0
956 public function setBackupStaticAttributes($backupStaticAttributes)
958 if (is_null($this->backupStaticAttributes) &&
959 is_bool($backupStaticAttributes)) {
960 $this->backupStaticAttributes = $backupStaticAttributes;
965 * Returns an iterator for this test suite.
967 * @return RecursiveIteratorIterator
969 * @since Method available since Release 3.1.0
971 public function getIterator()
973 $iterator = new PHPUnit_Util_TestSuiteIterator($this);
975 if ($this->iteratorFilter !== null) {
976 $iterator = $this->iteratorFilter->factory($iterator, $this);
982 public function injectFilter(PHPUnit_Runner_Filter_Factory $filter)
984 $this->iteratorFilter = $filter;
985 foreach ($this as $test) {
986 if ($test instanceof self) {
987 $test->injectFilter($filter);
993 * Template Method that is called before the tests
994 * of this test suite are run.
996 * @since Method available since Release 3.1.0
998 protected function setUp()
1003 * Template Method that is called after the tests
1004 * of this test suite have finished running.
1006 * @since Method available since Release 3.1.0
1008 protected function tearDown()