MINOR: added phpdoc to the new PHPUnitWrapper classes. (from r111042)

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@112880 467b73ca-7a2a-4603-9d3b-597d59a354a9

dev/TestRunner.php

@@ -20,16 +20,6 @@ class TestRunner extends Controller {
 	/** @ignore */
 	private static $default_reporter;
 	
-	public static $phpunit_wrapper = null;
-
-	static function set_phpunit_wrapper($value) {
-		self::$phpunit_wrapper = $value; 
-	}
-	
-	static function get_phpunit_wrapper() {
-		return self::$phpunit_wrapper;
-	}
-	
 	static $url_handlers = array(
 		'' => 'browse',
 		'coverage/module/$ModuleName' => 'coverageModule',
@@ -79,7 +69,7 @@ class TestRunner extends Controller {
 		
 		if (!self::$default_reporter) self::set_reporter(Director::is_cli() ? 'CliDebugView' : 'DebugView');
 		
-		if(!PhpUnitWrapper::hasPhpUnit()) {
+		if(!PhpUnitWrapper::has_php_unit()) {
 			die("Please install PHPUnit using pear");
 		}
 	}
@@ -271,7 +261,7 @@ class TestRunner extends Controller {
 		}
 
 		// perform unit tests (use PhpUnitWrapper or derived versions)
-		$phpunitwrapper = TestRunner::get_phpunit_wrapper();
+		$phpunitwrapper = PhpUnitWrapper::inst();
 		$phpunitwrapper->setSuite($suite);
 		$phpunitwrapper->setCoverageStatus($coverage);
 

dev/phpunit/PhpUnitWrapper.php

@@ -1,4 +1,8 @@
 <?php
+/**
+* @package sapphire
+* @subpackage dev
+*/
 
 /**
  * This method checks if a given filename exists in the include path (defined
@@ -15,95 +19,181 @@ function fileExistsInIncludePath($filename) {
 	return false;
 }
 
+/**
+ * PHPUnit Wrapper class.
+ * Base class for PHPUnit wrapper classes to support different PHPUnit versions.
+ * The current implementation supports PHPUnit 3.4 and PHPUnit 3.5.
+ */
 class PhpUnitWrapper implements IPhpUnitWrapper {
 	
+	/**
+	 * Flag if coverage report shall be generated or not.
+	 * @var boolean
+	 */	
 	private $coverage = false;
 	
+	/**
+	 * PHPUnit-TestSuite class. The tests, added to this suite are performed
+	 * in this test-run.
+	 * @var PHPUnit_Framework_TestSuite
+	 */	
 	private $suite = null;
 
+	/**
+	 * @var PHPUnit_Framework_TestResult
+	 */
 	private $results = null;
 
-	protected $version = 'none';
+	/**
-	
+	 * @var PHPUnit_Framework_TestListener
+	 */	
 	private $reporter = null;
 	
-	public function getVersion() {
+	/**
-		return $this->version;
+	 * Shows the version, implemented by the phpunit-wrapper class instance.
-	}
+	 * This instance implements no phpunit, the version is null.
+	 * @var String
+	 */	
+	protected $version = null;
 			
-	public function getFrameworkTestResults() {
+	private static $phpunit_wrapper = null;
-		return $this->results;
-	}
-	
-	public function setFrameworkTestResults($value) {
-		$this->results = $value;
-	}	
 
+	/** 
+	 * Getter for $coverage (@see $coverage).
+	 * @return boolean
+	 */
 	public function getCoverageStatus() {
 		return $this->coverage;
 	}
 	
+	/** 
+	 * Setter for $coverage (@see $coverage).
+	 * @parameter $value Boolean
+	 */	
 	public function setCoverageStatus($value) {
 		$this->coverage = $value;
 	}
 
+	/** 
+	 * Getter for $suite (@see $suite).
+	 * @return PHPUnit_Framework_TestSuite
+	 */	
 	public function getSuite() {
 		return $this->suite;
 	}
 	
-	public function setReporter($value) {
+	/** 
-		$this->reporter = $value;
+	 * Setter for $suite (@see $suite).
-	}
+	 * @param $value PHPUnit_Framework_TestSuite
-	
+	 */
-	public function getReporter() {
-		return $this->reporter;
-	}
-
 	public function setSuite($value) {
 		$this->suite = $value;
 	}
 	
+	/** 
+	 * Getter for $reporter (@see $reporter).
+	 * @return PHPUnit_Framework_TestListener
+	 */
+	public function getReporter() {
+		return $this->reporter;
+	}
 		
 	/** 
-	 *
+	 * Setter for $reporter (@see $reporter).
+	 * @param $value PHPUnit_Framework_TestListener
 	 */
-	static function getPhpUnit_Version() {
+	public function setReporter($value) {
-		$result = 'none';
+		$this->reporter = $value;
+	}
 	
-		if (TestRunner::get_phpunit_wrapper() == null) {
+	/** 
+	 * Getter for $results (@see $results).
+	 * @return PHPUnit_Framework_TestResult
+	 */
+	public function getFrameworkTestResults() {
+		return $this->results;
+	}
+	
+	/** 
+	 * Setter for $results (@see $results).
+	 * @param $value PHPUnit_Framework_TestResult
+	 */
+	public function setFrameworkTestResults($value) {
+		$this->results = $value;
+	}	
+
+	/** 
+	 * Getter for $version (@see $version).
+	 * @return String
+	 */	
+	public function getVersion() {
+		return $this->version;
+	}
+
+	/**
+	 * Loads and initiates phpunit, based on the available phpunit version.
+	 *
+	 * @return PhpUnitWrapper Instance of the php-wrapper class
+	 */
+	static function inst() {
+		
+		if (self::$phpunit_wrapper == null) {
 			 if (fileExistsInIncludePath("/PHPUnit/Autoload.php")) {
-			 	TestRunner::set_phpunit_wrapper(new PhpUnitWrapper_3_5());
+			 	self::$phpunit_wrapper = new PhpUnitWrapper_3_5();
 			 } else 
 			 if (fileExistsInIncludePath("/PHPUnit/Framework.php")) {
-			 	TestRunner::set_phpunit_wrapper(new PhpUnitWrapper_3_4());
+			 	self::$phpunit_wrapper = new PhpUnitWrapper_3_4();
 			 } else {
-			 	TestRunner::set_phpunit_wrapper(new PhpUnitWrapper());
+			 	self::$phpunit_wrapper = new PhpUnitWrapper();
 			 } 
-			TestRunner::get_phpunit_wrapper()->init();
+			self::$phpunit_wrapper->init();
 
 		}		
-		$result = TestRunner::get_phpunit_wrapper()->getVersion();
+		return self::$phpunit_wrapper;
-		return $result;
 	}	
 
 	/**
 	 * Returns true if one of the two supported PHPUNIT versions is installed.
+	 *
+	 * @return boolean true if PHPUnit has been installed on the environment.
 	 */
-	static function hasPhpUnit() {
+	static function has_php_unit() {
-		return (self::getPhpUnit_Version() != 'none');
+		return (Bool) self::inst()->getVersion();
 	}
 	
+	/** 
+	 * Implements method, defined in the interface IPhpUnitWrapper:init (@see IPhpUnitWrapper).
+	 * This wrapper class doesn't require any initialisation.
+	 */ 
 	public function init() {
 	}
 
+	/**
+	 * This method is called before the unittests are performed. 
+	 * This wrapper implements the non-PHPUnit version which means that unit tests
+	 * can not be performed. 
+	 * @throws PhpUnitWrapper_Excption
+	 */
 	protected function beforeRunTests() {
-		// throw new PhpUnitWrapper_Excption('Method \'beforeRunTests\' not implemented in PhpUnitWrapper.');
+		throw new PhpUnitWrapper_Exception('Method \'beforeRunTests\' not implemented in PhpUnitWrapper.');
 	}
 	
+	/**
+	 * This method is called after the unittests are performed. 
+	 * This wrapper implements the non-PHPUnit version which means that unit tests
+	 * can not be performed. 
+	 * @throws PhpUnitWrapper_Excption
+	 */
 	protected function afterRunTests() {
-		// throw new PhpUnitWrapper_Excption('Method \'afterRunTests\' not implemented in PhpUnitWrapper.');
+		throw new PhpUnitWrapper_Exception('Method \'afterRunTests\' not implemented in PhpUnitWrapper.');
 	}
 
+	/**
+	 * Perform all tests, added to the suite and initialises Sapphire to collect
+	 * the results of the unit tests.
+	 *
+	 * This method calls @see beforeRunTests and @see afterRunTests.
+	 */
 	public function runTests() {
 		
 		if(Director::is_cli()) {
@@ -121,19 +211,30 @@ class PhpUnitWrapper implements IPhpUnitWrapper {
 		$this->getSuite()->run($this->getFrameworkTestResults());
 		$this->aferRunTests();
 	}
-
 }
 
+/** 
+ * Interface, implementing the general PHPUnit wrapper API.
+ */
 interface IPhpUnitWrapper {
 
 	public function init();
 
 	public function runTests();
-	
 }
 
-// This class is here to help with documentation.
+
-if(!PhpUnitWrapper::hasPhpUnit()) {
+/**
+ * PHPUnitWrapper Exception class
+ */ 
+class PhpUnitWrapper_Exception extends Exception {}
+
+
+// If PHPUnit is not installed on the local environment, declare the class to 
+// ensure that missing class declarations are available to avoind any PHP fatal
+// errors.
+//
+if(!PhpUnitWrapper::has_php_unit()) {
 	/**
 	 * PHPUnit is a testing framework that can be installed using PEAR.
 	 * It's not bundled with Sapphire, you will need to install it yourself.

dev/phpunit/PhpUnitWrapper_3_4.php

@@ -1,15 +1,30 @@
 <?php
+/**
+* @package sapphire
+* @subpackage dev
+*/
 
+/**
+ * PHPUnit Wrapper class. Implements the correct behaviour for PHPUnit V3.4.
+ */
 class PhpUnitWrapper_3_4 extends PhpUnitWrapper {
 
 	protected $version = 'PhpUnit V3.4';
 
+	/** 
+	 * Initialise the wrapper class.
+	 */
 	public function init() {
+		parent::init();
 		require_once 'PHPUnit/Framework.php';
 		require_once 'PHPUnit/Util/Report.php';
 		require_once 'PHPUnit/TextUI/TestRunner.php';
 	}
 	
+	/**
+	 * Overwrites beforeRunTests. Initiates coverage-report generation if 
+	 * $coverage has been set to true (@see setCoverageStatus).
+	 */
 	protected function beforeRunTests() {
 
 		if($this->getCoverageStatus()) {
@@ -21,18 +36,19 @@ class PhpUnitWrapper_3_4 extends PhpUnitWrapper {
 		}
 	}
 
+	/**
+	 * Overwrites aferRunTests. Creates coverage report and clover report 
+	 * if required.
+	 */
 	protected function aferRunTests() {
 
 		if($this->getCoverageStatus()) {
-	        require_once 'PHPUnit/Util/Log/CodeCoverage/XML/Clover.php';
-	        $writer = new PHPUnit_Util_Log_CodeCoverage_XML_Clover('clover.xml');
-	        $writer->process($this->getFrameworkTestResults());
 
 			if(!file_exists(ASSETS_PATH . '/coverage-report')) {
 				mkdir(ASSETS_PATH . '/coverage-report');
 			}
 
-			PHPUnit_Util_Report::render($this->getFrameworkTestResults(), ASSETS_PATH . '/coverage-report/');
+			$ret = PHPUnit_Util_Report::render($this->getFrameworkTestResults(), ASSETS_PATH . '/coverage-report/');
 
 			$coverageApp = ASSETS_PATH . '/coverage-report/' . preg_replace('/[^A-Za-z0-9]/','_',preg_replace('/(\/$)|(^\/)/','',Director::baseFolder())) . '.html';
 			$coverageTemplates = ASSETS_PATH . '/coverage-report/' . preg_replace('/[^A-Za-z0-9]/','_',preg_replace('/(\/$)|(^\/)/','',realpath(TEMP_FOLDER))) . '.html';
@@ -44,8 +60,4 @@ class PhpUnitWrapper_3_4 extends PhpUnitWrapper {
 		}
 	}
 	
-	public function runTests() {
-		return parent::runTests();
-	}
-	
 }

dev/phpunit/PhpUnitWrapper_3_5.php

@@ -1,4 +1,8 @@
 <?php
+/**
+* @package sapphire
+* @subpackage dev
+*/
 
 class PhpUnitWrapper_3_5 extends PhpUnitWrapper {
 
@@ -8,46 +12,31 @@ class PhpUnitWrapper_3_5 extends PhpUnitWrapper {
 
 	protected static $test_name = 'SapphireTest';
 
-	protected static $generate_clover = false;
-
-	protected static $clover_filename = 'clover.xml';
-	
 	static function get_test_name() {
 		return self::$test_name;
 	}
 
-	static function get_generate_clover() {
+	/** 
-		return self::$generate_clover;
+	 * Initialise the wrapper class.
-	}
+	 */
-
-	static function set_generate_clover($value) {
-		self::$generate_clover = $value;
-	}
-	
-	static function get_clover_filename() {
-		return self::$clover_filename;
-	}
-	
-	static function set_clover_filename($value) {
-		self::$clover_filename = $value;
-	}
-
 	public function init() {
 		require_once 'PHP/CodeCoverage.php';
-		require_once 'PHP/CodeCoverage/Report/Clover.php';
 		require_once 'PHP/CodeCoverage/Report/HTML.php';
 
 		require_once 'PHPUnit/Autoload.php';
 
 		require_once 'PHP/CodeCoverage/Filter.php';
 		PHP_CodeCoverage_Filter::getInstance()->addFileToBlacklist(__FILE__, 'PHPUNIT');
-
 	}
 	
+	/**
+	 * Overwrites beforeRunTests. Initiates coverage-report generation if 
+	 * $coverage has been set to true (@see setCoverageStatus).
+	 */
 	protected function beforeRunTests() {
 		
 		if($this->getCoverageStatus()) {			
-            $this->coverage = new PHP_CodeCoverage;
+            $this->coverage = new PHP_CodeCoverage();
 			$coverage = $this->coverage;
 
             $filter = $coverage->filter();
@@ -60,25 +49,19 @@ class PhpUnitWrapper_3_5 extends PhpUnitWrapper {
 		}
 	}
 
+	/**
+	 * Overwrites aferRunTests. Creates coverage report and clover report 
+	 * if required.
+	 */
 	protected function aferRunTests() {
 
 		if($this->getCoverageStatus()) {
 			$coverage = $this->coverage;
 			$coverage->stop();
 				
-			if (self::get_generate_clover() == true) {
+			$writer = new PHP_CodeCoverage_Report_HTML();
-				
-				$filename = self::get_clover_filename();
-				$writer = new PHP_CodeCoverage_Report_Clover;
-				$writer->process($coverage, ASSETS_PATH."/".$filename);
-			}
-
-			$writer = new PHP_CodeCoverage_Report_HTML;
 			$writer->process($coverage, ASSETS_PATH.'/code-coverage-report');
 		}
 	}
 
-	public function runTests() {
-		return parent::runTests();
-	}
 }