Add testcase method's name to the test's title. (#451)

Resolves #448.

src/Framework/Helpers.php

@@ -71,7 +71,7 @@ public static function findCommonDirectory(array $paths): string
 
 
 	/**
-	 * Parse phpDoc comment.
+	 * Parse the first docblock encountered in the provided string.
 	 * @internal
 	 */
 	public static function parseDocComment(string $s): array
@@ -81,10 +81,14 @@ public static function parseDocComment(string $s): array
 			return [];
 		}
 
+		// The first non-@tagged string encountered in a multiline docblock will
+		// be stored at index 0.
 		if (preg_match('#^[ \t\*]*+([^\s@].*)#mi', $content[1], $matches)) {
 			$options[0] = trim($matches[1]);
 		}
 
+		// Parse @tags and their arguments. If there are multiple identically
+		// named tags, their arguments will be returned as a list of string.
 		preg_match_all('#^[ \t\*]*@(\w+)([^\w\r\n].*)?#mi', $content[1], $matches, PREG_SET_ORDER);
 		foreach ($matches as $match) {
 			$ref = &$options[strtolower($match[1])];

src/Runner/Test.php

@@ -43,7 +43,7 @@ class Test
 	public function __construct(string $file, ?string $title = null)
 	{
 		$this->file = $file;
-		$this->title = $title;
+		$this->title = $title !== null ? trim($title) : null;
 	}
 
 
@@ -100,6 +100,29 @@ public function getOutput(): string
 	}
 
 
+	public function withAppendedTitle(string $title): self
+	{
+		if ($this->hasResult()) {
+			throw new \LogicException('Cannot append title to test which already has a result.');
+		}
+
+		$title = trim($title);
+		$me = clone $this;
+
+		if ($title === '') {
+			return $me;
+		}
+
+		// At this point we're sure both $me->title and $title do not have
+		// leading/trailing whitespace.
+		$me->title = $me->title !== null
+			? "{$me->title} {$title}"
+			: $title;
+
+		return $me;
+	}
+
+
 	/**
 	 * @return static
 	 */

src/Runner/TestHandler.php

@@ -228,7 +228,10 @@ private function initiateTestCase(Test $test, $foo, PhpInterpreter $interpreter)
 		}
 
 		return array_map(
-			fn(string $method): Test => $test->withArguments(['method' => $method]),
+			fn(string $method): Test => $test
+				// Add the testcase method's name to the test's title.
+				->withAppendedTitle($method)
+				->withArguments(['method' => $method]),
 			$methods,
 		);
 	}

tests/Runner/Job.phpt

@@ -28,3 +28,29 @@ test('', function () {
 		Assert::contains('Nette Tester', $job->getHeaders());
 	}
 });
+
+
+test('Appending title to a Test object w/o initial title', function () {
+	$testA = (new Test('Job.test.phptx'));
+	Assert::null($testA->title);
+
+	$testB = $testA->withAppendedTitle('title B');
+	Assert::notSame($testB, $testA);
+	Assert::same('title B', $testB->title);
+
+	$testC = $testB->withAppendedTitle(" \t    title C  ");
+	Assert::notSame($testC, $testB);
+	Assert::same('title B title C', $testC->title);
+});
+
+
+test('Appending title to a Test object w/ initial title', function () {
+	$testA = (new Test('Job.test.phptx', 'Initial title   '));
+	Assert::same('Initial title', $testA->title);
+
+	$testB = $testA->withAppendedTitle('   ');
+	Assert::same('Initial title', $testB->title);
+
+	$testC = $testB->withAppendedTitle(" \t    MEGATITLE  ");
+	Assert::same('Initial title MEGATITLE', $testC->title);
+});