Merge pull request #372 from PHPCSStandards/testutils/utilitymethodte…

…stcase-gettargettoken-throw-on-missing-marker

UtilityMethodTestCase::getTargetToken(): throw an exception when delimiter not found

PHPCSUtils/Exceptions/TestMarkerNotFound.php

@@ -0,0 +1,43 @@
+<?php
+/**
+ * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSUtils
+ * @copyright 2019-2020 PHPCSUtils Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSUtils
+ */
+
+namespace PHPCSUtils\Exceptions;
+
+use OutOfBoundsException;
+
+/**
+ * Exception thrown when a delimiter comment can not be found in a test case file.
+ *
+ * @since 1.0.0-alpha4
+ */
+final class TestMarkerNotFound extends OutOfBoundsException
+{
+
+    /**
+     * Create a new "test marker not found" exception with a standardized text.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param string $marker The delimiter comment.
+     * @param string $file   The file in which the delimiter was not found.
+     *
+     * @return \PHPCSUtils\Exceptions\TestMarkerNotFound
+     */
+    public static function create($marker, $file)
+    {
+        return new self(
+            \sprintf(
+                'Failed to find the test marker: %s in test case file %s',
+                $marker,
+                $file
+            )
+        );
+    }
+}

PHPCSUtils/TestUtils/UtilityMethodTestCase.php

@@ -12,6 +12,7 @@
 
 use PHP_CodeSniffer\Exceptions\TokenizerException;
 use PHPCSUtils\BackCompat\Helper;
+use PHPCSUtils\Exceptions\TestMarkerNotFound;
 use PHPCSUtils\Exceptions\TestTargetNotFound;
 use PHPUnit\Framework\TestCase;
 use ReflectionClass;
@@ -325,9 +326,9 @@ public static function usesPhp8NameTokens()
      * Note: the test delimiter comment MUST start with `/* test` to allow this function to
      * distinguish between comments used *in* a test and test delimiters.
      *
-     * If the delimiter comment is not found, the test will automatically be failed.
-     *
      * @since 1.0.0
+     * @since 1.0.0-alpha4 Will throw an exception whether the delimiter comment or the target
+     *                     token is not found.
      *
      * @param string           $commentString The complete delimiter comment to look for as a string.
      *                                        This string should include the comment opener and closer.
@@ -336,6 +337,7 @@ public static function usesPhp8NameTokens()
      *
      * @return int
      *
+     * @throws \PHPCSUtils\Exceptions\TestMarkerNotFound When the delimiter comment for the test was not found.
      * @throws \PHPCSUtils\Exceptions\TestTargetNotFound When the target token cannot be found.
      */
     public function getTargetToken($commentString, $tokenType, $tokenContent = null)
@@ -350,8 +352,7 @@ public function getTargetToken($commentString, $tokenType, $tokenContent = null)
         );
 
         if ($comment === false) {
-            $msg = 'Failed to find the test marker: ' . $commentString;
-            $this->fail($msg);
+            throw TestMarkerNotFound::create($commentString, self::$phpcsFile->getFilename());
         }
 
         $tokens = self::$phpcsFile->getTokens();

Tests/Exceptions/TestMarkerNotFound/TestMarkerNotFoundTest.php

@@ -0,0 +1,38 @@
+<?php
+/**
+ * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSUtils
+ * @copyright 2019-2020 PHPCSUtils Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSUtils
+ */
+
+namespace PHPCSUtils\Tests\Exceptions\TestMarkerNotFound;
+
+use PHPCSUtils\Exceptions\TestMarkerNotFound;
+use Yoast\PHPUnitPolyfills\TestCases\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Exceptions\TestMarkerNotFound
+ *
+ * @since 1.0.0
+ */
+final class TestMarkerNotFoundTest extends TestCase
+{
+
+    /**
+     * Test that the text of the exception is as expected.
+     *
+     * @return void
+     */
+    public function testCreate()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\TestMarkerNotFound');
+        $this->expectExceptionMessage('Failed to find the test marker: /* testDummy */ in test case file filename.inc');
+
+        throw TestMarkerNotFound::create('/* testDummy */', 'filename.inc');
+    }
+}

Tests/TestUtils/UtilityMethodTestCase/GetTargetTokenTest.php

@@ -131,15 +131,8 @@ public function dataGetTargetToken()
      */
     public function testGetTargetTokenCommentNotFound()
     {
-        $msg       = 'Failed to find the test marker: ';
-        $exception = 'PHPUnit\Framework\AssertionFailedError';
-        if (\class_exists('PHPUnit_Framework_AssertionFailedError')) {
-            // PHPUnit < 6.
-            $exception = 'PHPUnit_Framework_AssertionFailedError';
-        }
-
-        $this->expectException($exception);
-        $this->expectExceptionMessage($msg);
+        $this->expectException('PHPCSUtils\Exceptions\TestMarkerNotFound');
+        $this->expectExceptionMessage('Failed to find the test marker: ');
 
         $this->getTargetToken('/* testCommentDoesNotExist */', [\T_VARIABLE], '$a');
     }