comments

src/TUnit/framework/test/TestCase.php

@@ -1,42 +1,153 @@
 <?php
 
+	/**
+	 * TestCase
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
+
+	/**
+	 * Represents a test case (collection of test methods)
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
 	class TestCase implements Testable {
 		
+		/**
+		 * Name of the test
+		 *
+		 * @var string
+		 */
 		protected $name;
-		private   $autoVerify;
 		
+		/**
+		 * Whether to automatically verify this test
+		 *
+		 * @var bool
+		 */
+		private $autoVerify;
+		
+		/**
+		 * Local cache of testable methods
+		 *
+		 * @var array
+		 */
 		private $testableMethods;
 		
+		/**
+		 * Mock invocation count
+		 *
+		 * @var int
+		 */
 		const ANY           = -1;
+		
+		/**
+		 * Mock invocation count
+		 *
+		 * @var int
+		 */
 		const AT_LEAST_ONCE = -2;
 		
 		
+		/**
+		 * Constructor
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  string $name
+		 */
 		public function __construct($name) {
 			$this->name            = $name;
 			$this->autoVerify      = true;
 			$this->testableMethods = array();
 		}
 		
+		/**
+		 * Gets the name of the name of this test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return string
+		 */
 		public final function getName() {
 			return $this->name;
 		}
 		
+		/**
+		 * Gets whether this test will automatically verify itself
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return bool
+		 */
 		public final function getAutoVerify() {
 			return $this->autoVerify;
 		}
 		
+		/**
+		 * Sets whether this test will automatically verify itself
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  bool $autoVerify
+		 */
 		public final function setAutoVerify($autoVerify) {
 			$this->autoVerify = (bool)$autoVerify;
 		}
 		
+		/**
+		 * Called before this test runs
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 */
 		protected function setUp() {
 			
 		}
 		
+		/**
+		 * Called after this test runs
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 */
 		protected function tearDown() {
 		
 		}
 		
+		/**
+		 * Runs the test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    TestListener::beforeTestCase()
+		 * @uses    getTestableMethods()
+		 * @uses    setUp()
+		 * @uses    CombinedTestResult::addTestResult()
+		 * @uses    TestMethod::run()
+		 * @uses    tearDown()
+		 * @uses    TestListener::afterTestCase()
+		 * 
+		 * @param  array $listeners Array of {@link TestListener}s
+		 * @return CombinedTestResult
+		 */
 		public function run(array $listeners) {
 			foreach ($listeners as $listener) {
 				$listener->beforeTestCase($this);
@@ -56,6 +167,17 @@
 			return $result;
 		}
 		
+		/**
+		 * Gets testable methods
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    Util::getClosure()
+		 * @uses    getAutoVerify()
+		 * 
+		 * @return array Array of {@link TestMethod}s
+		 */
 		public final function getTestableMethods() {
 			if (empty($this->testableMethods)) {
 				$refClass = new ReflectionClass($this);
@@ -75,6 +197,21 @@
 			return $this->testableMethods;
 		}
 		
+		/**
+		 * Creates a default mock object
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    MockObjectCreator::addMethod
+		 * 
+		 * @param  string $className  The name of the class to mock
+		 * @param  array  $methods    The methods to mock
+		 * @param  array  $args       The constructor arguments
+		 * @param  string $name       The name of the mocked class, by default a random name is chosen
+		 * @param  bool   $callParent Whether to call the parent constructor or not
+		 * @return object A subclass of $className
+		 */
 		protected function createMockObject($className, array $methods = array(), array $args = array(), $name = '', $callParent = true) {
 			$creator = new MockObjectCreator($className, $callParent);
 			
@@ -85,24 +222,75 @@
 			return $creator->generate($args, $name);
 		}
 		
+		/**
+		 * Wrapper for interacting with the mock object framework
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  MockObject $mock
+		 * @return MockHandler
+		 */
 		protected function mock(MockObject $mock) {
 			return new MockHandler($mock);
 		}
 		
+		/**
+		 * Ignores the test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  string $message
+		 * @throws {@link IgnoredTest}
+		 */
 		protected function ignore($message = '') {
 			throw new IgnoredTest($message);
 		}
 		
+		/**
+		 * Fails the test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  string $message
+		 * @throws {@link FailedTest}
+		 */
 		protected function fail($message = '') {
 			throw new FailedTest($message);
 		}
 		
+		/**
+		 * Gets the number of testable methods
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    getTestableMethods()
+		 * 
+		 * @return count
+		 */
 		public function count() {
 			return count($this->getTestableMethods());
 		}
 		
+		/**
+		 * Gets the number of test suites, casese and methods in this test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    Util::countTests()
+		 * @uses    getTestableMethods()
+		 * 
+		 * @return array
+		 */
 		public function getTestCount() {
-			return Util::countTests($this->testableMethods);
+			return Util::countTests($this->getTestableMethods());
 		}
 		
 	}

src/TUnit/framework/test/TestMethod.php

@@ -1,21 +1,92 @@
 <?php
 
+	/**
+	 * TestMethod
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
+
+	/**
+	 * Represents a single test method
+	 *
+	 * This class should only be used internally by the TUnit framework.
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
 	/* internal */ class TestMethod implements Testable {
 		
+		/**
+		 * @var bool
+		 */
 		protected $autoVerify;
+		
+		/**
+		 * @var lambda
+		 */
 		protected $closure;
+		
+		/**
+		 * Name of this test
+		 *
+		 * @var mixed
+		 */
 		protected $name;
 		
+		/**
+		 * Constructor
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  lambda $closure    A closure around a testable method
+		 * @param  string $name       Name of the test
+		 * @param  bool   $autoVerify
+		 */
 		public function __construct($closure, $name, $autoVerify) {
 			$this->closure    = $closure;
 			$this->autoVerify = (bool)$autoVerify;
 			$this->name       = $name;
 		}
 		
-		public function getName() {
+		/**
+		 * Gets the name of this test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return string
+		 */
+		public final function getName() {
 			return $this->name;
 		}
 		
+		/**
+		 * Runs the test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    TestListener::beforeTestMethod()
+		 * @uses    MockRegistry::getTrackers()
+		 * @uses    InvocationTracker::verify()
+		 * @uses    TestListener::onTestMethodPassed()
+		 * @uses    handlTestFailure()
+		 * @uses    TestListener::onTestMethodErred()
+		 * @uses    createTestResult()
+		 * @uses    TestListener::afterTestMethod()
+		 * @uses    MockRegistry::reset()
+		 * 
+		 * @param  array $listeners
+		 * @return TestResult
+		 */
 		public function run(array $listeners) {
 			foreach ($listeners as $listener) {
 				$listener->beforeTestMethod($this);
@@ -62,6 +133,17 @@
 			return $result;
 		}
 		
+		/**
+		 * Creates a test result
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  Exception $failure
+		 * @throws InvalidArgumentException
+		 * @return TestResult
+		 */
 		protected function createTestResult(Exception $failure = null) {
 			if ($failure === null) {
 				return new PassedTestResult($this);
@@ -76,6 +158,19 @@
 			throw new InvalidArgumentException('Unknown test failure type: ' . get_class($failure));
 		}
 		
+		/**
+		 * Handles a test failure
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    TestListener::onTestMethodFailed()
+		 * @uses    TestListener::onTestMethodIgnored()
+		 * @uses    TestListener::onTestMethodErred()
+		 * 
+		 * @param  TestFailure $failure
+		 * @param  array       $listeners
+		 */
 		protected function handleTestFailure(TestFailure $failure, array $listeners) {
 			if ($failure instanceof FailedTest) {
 				foreach ($listeners as $listener) {
@@ -92,10 +187,29 @@
 			}
 		}
 		
+		/**
+		 * Gets the number of tests
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return int Always returns one
+		 */
 		public function count() {
 			return 1;
 		}
 		
+		/**
+		 * Gets the number of suites, cases and methods
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    Util::countTests()
+		 * 
+		 * @return array
+		 */
 		public function getTestCount() {
 			return Util::countTests(array($this));
 		}

src/TUnit/framework/test/TestSuite.php

@@ -1,36 +1,133 @@
 <?php
 
+	/**
+	 * TestSuite
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
+
+	/**
+	 * Represents a collection of test suites, test cases and/or
+	 * test methods
+	 *
+	 * @package TUnit
+	 * @author  Tommy Montgomery
+	 * @version 1.0
+	 * @since   1.0
+	 */
 	class TestSuite implements Testable {
 		
+		/**
+		 * The name of this test
+		 *
+		 * @var string
+		 */
 		protected $name;
+		
+		/**
+		 * The tests contained in with this suite
+		 *
+		 * @var array
+		 */
 		protected $tests;
 		
+		/**
+		 * Constructor
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  mixed $name  Name of the test suite
+		 * @param  array $tests Tests contained in this test suite
+		 */
 		public function __construct($name, array $tests = array()) {
 			$this->name  = $name;
 			$this->tests = $tests;
 		}
 		
-		public function getName() {
+		/**
+		 * Gets the name of this test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return string
+		 */
+		public final function getName() {
 			return $this->name;
 		}
 		
+		/**
+		 * Called before the test suite runs
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 */
 		protected function setUp() {
 		
 		}
 		
+		/**
+		 * Called after the test suite runs
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 */
 		protected function tearDown() {
 		
 		}
 		
+		/**
+		 * Adds a test
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @param  Testable $test
+		 * @return TestSuite
+		 */
 		public final function addTest(Testable $test) {
 			$this->tests[] = $test;
 			return $this;
 		}
 		
+		/**
+		 * Gets all tests
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return array
+		 */
 		public final function getTests() {
 			return $this->tests;
 		}
 		
+		/**
+		 * Runs the test suite
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    TestListener::beforeTestSuite()
+		 * @uses    setUp()
+		 * @uses    CombinedTestResult::addTestResult()
+		 * @uses    TestListener::onFrameworkWarning()
+		 * @uses    tearDown()
+		 * @uses    TestListener::afterTestSuite()
+		 * 
+		 * @param  array $listeners Array of {@link TestListener}s
+		 * @return CombinedTestResult
+		 */
 		public function run(array $listeners) {
 			foreach ($listeners as $listener) {
 				$listener->beforeTestSuite($this);
@@ -57,10 +154,29 @@
 			return $result;
 		}
 		
+		/**
+		 * Gets the number of tests
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * 
+		 * @return int
+		 */
 		public function count() {
 			return count($this->tests);
 		}
 		
+		/**
+		 * Gets the number of test suites, cases and methods
+		 *
+		 * @author  Tommy Montgomery
+		 * @version 1.0
+		 * @since   1.0
+		 * @uses    Util::countTests()
+		 * 
+		 * @return array
+		 */
 		public function getTestCount() {
 			return Util::countTests($this->tests);
 		}