Deprecate TestCase

Added some more docs and tests.

Author: trowski

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 () {