UtilityMethodTestCase::getTargetToken(): throw exception when method called without tokenized test case file

PHPCSUtils/Exceptions/TestFileNotFound.php

@@ -0,0 +1,47 @@
+<?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 BadMethodCallException;
+
+/**
+ * Exception thrown when the UtilityMethodTestCase::getTargetToken() method is run without a
+ * tokenized test case file being available.
+ *
+ * @since 1.0.0-alpha4
+ */
+final class TestFileNotFound extends BadMethodCallException
+{
+
+    /**
+     * Create a new "test file not found" exception with a standardized text.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param string          $message  The Exception message to throw.
+     * @param int             $code     The Exception code.
+     * @param \Throwable|null $previous The previous exception used for the exception chaining.
+     *
+     * @return void
+     */
+    public function __construct($message = '', $code = 0, $previous = null)
+    {
+        if ($message === '') {
+            $message = \sprintf(
+                'Failed to find a tokenized test case file.%sMake sure the UtilityMethodTestCase::setUpTestFile()'
+                . ' method has run before calling UtilityMethodTestCase::getTargetToken()',
+                \PHP_EOL
+            );
+        }
+
+        parent::__construct($message, $code, $previous);
+    }
+}

PHPCSUtils/TestUtils/UtilityMethodTestCase.php

@@ -11,7 +11,9 @@
 namespace PHPCSUtils\TestUtils;
 
 use PHP_CodeSniffer\Exceptions\TokenizerException;
+use PHP_CodeSniffer\Files\File;
 use PHPCSUtils\BackCompat\Helper;
+use PHPCSUtils\Exceptions\TestFileNotFound;
 use PHPCSUtils\Exceptions\TestMarkerNotFound;
 use PHPCSUtils\Exceptions\TestTargetNotFound;
 use PHPUnit\Framework\TestCase;
@@ -343,6 +345,10 @@ public static function usesPhp8NameTokens()
      */
     public static function getTargetToken($commentString, $tokenType, $tokenContent = null)
     {
+        if ((self::$phpcsFile instanceof File) === false) {
+            throw new TestFileNotFound();
+        }
+
         $start   = (self::$phpcsFile->numTokens - 1);
         $comment = self::$phpcsFile->findPrevious(
             \T_COMMENT,

Tests/Exceptions/TestFileNotFound/TestFileNotFoundTest.php

@@ -0,0 +1,54 @@
+<?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\TestFileNotFound;
+
+use PHPCSUtils\Exceptions\TestFileNotFound;
+use Yoast\PHPUnitPolyfills\TestCases\TestCase;
+
+/**
+ * Test class.
+ *
+ * @covers \PHPCSUtils\Exceptions\TestFileNotFound
+ *
+ * @since 1.0.0
+ */
+final class TestFileNotFoundTest extends TestCase
+{
+
+    /**
+     * Test that the text of the exception is as expected.
+     *
+     * @return void
+     */
+    public function testNoCustomMessage()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\TestFileNotFound');
+        $this->expectExceptionMessage(
+            'Failed to find a tokenized test case file.' . \PHP_EOL
+            . 'Make sure the UtilityMethodTestCase::setUpTestFile() method has run'
+        );
+
+        throw new TestFileNotFound();
+    }
+
+    /**
+     * Test that a passed message overruled the default message.
+     *
+     * @return void
+     */
+    public function testWithCustomMessage()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\TestFileNotFound');
+        $this->expectExceptionMessage('foobar');
+
+        throw new TestFileNotFound('foobar');
+    }
+}

Tests/TestUtils/UtilityMethodTestCase/GetTargetTokenFileNotFoundTest.php

@@ -0,0 +1,54 @@
+<?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\TestUtils\UtilityMethodTestCase;
+
+use PHPCSUtils\Tests\PolyfilledTestCase;
+
+/**
+ * Tests for the \PHPCSUtils\TestUtils\UtilityMethodTestCase::getTargetToken() method.
+ *
+ * @covers \PHPCSUtils\TestUtils\UtilityMethodTestCase::getTargetToken
+ *
+ * @group testutils
+ *
+ * @since 1.0.0
+ */
+final class GetTargetTokenFileNotFoundTest extends PolyfilledTestCase
+{
+
+    /**
+     * Overload the "normal" set up to prevent a test case file from being tokenized.
+     *
+     * @beforeClass
+     *
+     * @return void
+     */
+    public static function setUpTestFile()
+    {
+        // Deliberately left empty.
+    }
+
+    /**
+     * Test the behaviour of the getTargetToken() method when the test case file has not been tokenized.
+     *
+     * @return void
+     */
+    public function testGetTargetTokenFileNotFound()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\TestFileNotFound');
+        $this->expectExceptionMessage(
+            'Failed to find a tokenized test case file.' . \PHP_EOL
+            . 'Make sure the UtilityMethodTestCase::setUpTestFile() method has run'
+        );
+
+        $this->getTargetToken('/* testSomething */', [\T_VARIABLE], '$a');
+    }
+}