Deprecate TestCase

Added some more docs and tests.

src/AsyncTestCase.php

@@ -15,24 +15,31 @@ abstract class AsyncTestCase extends PHPUnitTestCase
 {
     const RUNTIME_PRECISION = 2;
 
+    /** @var string|null Timeout watcher ID. */
     private $timeoutId;
 
+    /** @var string Temporary storage for actual test name. */
     private $realTestName;
 
-    private $minimumRuntime;
+    /** @var int Minimum runtime in milliseconds. */
+    private $minimumRuntime = 0;
 
-    public function setName($name)
+    /**
+     * @codeCoverageIgnore Invoked before code coverage data is being collected.
+     */
+    final public function setName($name)
     {
         parent::setName($name);
         $this->realTestName = $name;
     }
 
-    protected function runTest()
+    final protected function runTest()
     {
         parent::setName('runAsyncTest');
         return parent::runTest();
     }
 
+    /** @internal */
     final public function runAsyncTest(...$args)
     {
         parent::setName($this->realTestName);
@@ -65,11 +72,21 @@ final public function runAsyncTest(...$args)
         return $returnValue;
     }
 
+    /**
+     * Fails the test if the loop does not run for at least the given amount of time.
+     *
+     * @param int $runtime Required run time in milliseconds.
+     */
     final protected function setMinimumRuntime(int $runtime)
     {
         $this->minimumRuntime = $runtime;
     }
 
+    /**
+     * Fails the test (and stops the loop) after the given timeout.
+     *
+     * @param int $timeout Timeout in milliseconds.
+     */
     final protected function setTimeout(int $timeout)
     {
         $this->timeoutId = Loop::delay($timeout, function () use ($timeout) {

src/LoopReset.php

@@ -6,6 +6,9 @@
 use PHPUnit\Framework\BaseTestListener;
 use PHPUnit\Framework\Test;
 
+/**
+ * @deprecated Use AsyncTestCase. TestListeners are now deprecated in PHPUnit.
+ */
 class LoopReset extends BaseTestListener
 {
     public function endTest(Test $test, $time)

src/TestCase.php

@@ -4,6 +4,8 @@
 
 /**
  * Abstract test class with methods for creating callbacks and asserting runtimes.
+ *
+ * @deprecated Use AsyncTestCase instead.
  */
 abstract class TestCase extends \PHPUnit\Framework\TestCase
 {

test/AsyncTestCaseTest.php

@@ -6,12 +6,13 @@
 use Amp\Delayed;
 use Amp\Loop;
 use Amp\PHPUnit\AsyncTestCase;
+use Amp\Promise;
 use PHPUnit\Framework\AssertionFailedError;
 use function Amp\call;
 
 class AsyncTestCaseTest extends AsyncTestCase
 {
-    public function testThatMethodRunsInLoopContext()
+    public function testThatMethodRunsInLoopContext(): Promise
     {
         $returnDeferred = new Deferred(); // make sure our test runs to completion
         $testDeferred = new Deferred(); // used by our defer callback to ensure we're running on the Loop
@@ -26,7 +27,7 @@ public function testThatMethodRunsInLoopContext()
         return $returnDeferred->promise();
     }
 
-    public function testThatWeHandleNotPromiseReturned()
+    public function testThatWeHandleNotPromiseReturned(): \Generator
     {
         $testDeferred = new Deferred();
         $testData = new \stdClass();
@@ -41,7 +42,7 @@ public function testThatWeHandleNotPromiseReturned()
         $this->assertTrue($testData->val, 'Expected our test to run on loop to completion');
     }
 
-    public function testExpectingAnExceptionThrown()
+    public function testExpectingAnExceptionThrown(): \Generator
     {
         $throwException = function () {
             return call(function () {
@@ -56,7 +57,7 @@ public function testExpectingAnExceptionThrown()
         yield $throwException();
     }
 
-    public function argumentSupportProvider()
+    public function argumentSupportProvider(): array
     {
         return [
             ['foo', 42, true],
@@ -77,7 +78,17 @@ public function testArgumentSupport(string $foo, int $bar, bool $baz)
         $this->assertTrue($baz);
     }
 
-    public function testSetMinimumRunTime()
+    public function testSetTimeout(): \Generator
+    {
+        $this->setTimeout(100);
+
+        $this->expectException(AssertionFailedError::class);
+        $this->expectExceptionMessage('Expected test to complete before 100ms time limit');
+
+        yield new Delayed(200);
+    }
+
+    public function testSetMinimumRunTime(): \Generator
     {
         $this->setMinimumRuntime(100);
         $func = function () {