PHPCSUtils

UtilityMethodTestCase extends TestCase
in package

Base class for use when testing utility methods for PHP_CodeSniffer.

This class is compatible with PHP_CodeSniffer 3.x and contains preliminary compatibility with 4.x based on its currently known state/roadmap.

This class is compatible with PHPUnit 4.5 - 9.x providing the PHPCSUtils autoload file is included in the test bootstrap. For more information about that, please consult the project's README.

To allow for testing of tab vs space content, the tabWidth is set to 4 by default.

Typical usage:

Test case file path/to/ClassUnderTestUnitTest.inc:

<?php

/* testTestCaseDescription * /
const BAR = false;

Test file path/to/ClassUnderTestUnitTest.php:

<?php

use PHPCSUtils\TestUtils\UtilityMethodTestCase;
use YourStandard\ClassUnderTest;

class ClassUnderTestUnitTest extends UtilityMethodTestCase {

    /**
     * Testing utility method MyMethod.
     *
     * @dataProvider dataMyMethod
     *
     * @covers \YourStandard\ClassUnderTest::MyMethod
     *
     * @param string $commentString The comment which prefaces the target token in the test file.
     * @param string $expected      The expected return value.
     *
     * @return void
     * /
    public function testMyMethod($commentString, $expected)
    {
        $stackPtr = $this->getTargetToken($commentString, [\T_TOKEN_CONSTANT, \T_ANOTHER_TOKEN]);
        $class    = new ClassUnderTest();
        $result   = $class->MyMethod(self::$phpcsFile, $stackPtr);
        // Or for static utility methods:
        $result   = ClassUnderTest::MyMethod(self::$phpcsFile, $stackPtr);

        $this->assertSame($expected, $result);
    }

    /**
     * Data Provider.
     *
     * @see ClassUnderTestUnitTest::testMyMethod() For the array format.
     *
     * @return array
     * /
    public function dataMyMethod()
    {
        return array(
            array('/* testTestCaseDescription * /', false),
        );
    }
}

Note:

  • Remove the space between the comment closers * / for a working example.
  • Each test case separator comment MUST start with /* test. This is to allow the UtilityMethodTestCase::getTargetToken() method to distinquish between the test separation comments and comments which may be part of the test case.
  • The test case file and unit test file should be placed in the same directory.
  • For working examples using this abstract class, have a look at the unit tests for the PHPCSUtils utility functions themselves.
Tags
since
1.0.0
since
1.0.0-alpha4

Dropped support for PHPCS < 3.7.1.

Table of Contents

$caseFile  : string
Full path to the test case file associated with the concrete test class.
$fileExtension  : string
The file extension of the test case file (without leading dot).
$phpcsFile  : File
The \PHP_CodeSniffer\Files\File object containing the parsed contents of the test case file.
$phpcsVersion  : string
The PHPCS version the tests are being run on.
$selectedSniff  : array<string|int, mixed>
Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).
$tabWidth  : int
The tab width setting to use when tokenizing the file.
expectPhpcsException()  : void
Helper method to tell PHPUnit to expect a PHPCS Exception in a PHPUnit and PHPCS cross-version compatible manner.
getTargetToken()  : int
Get the token pointer for a target token based on a specific comment.
resetTestFile()  : void
Clean up after finished test by resetting all static properties to their default values.
setUpTestFile()  : void
Initialize PHPCS & tokenize the test case file.
skipJSCSSTestsOnPHPCS4()  : void
Skip JS and CSS related tests on PHPCS 4.x.
usesPhp8NameTokens()  : bool
Check whether or not the PHP 8.0 identifier name tokens will be in use.

Properties

$caseFile

Full path to the test case file associated with the concrete test class.

protected static string $caseFile = ''

Optional. If left empty, the case file will be presumed to be in the same directory and named the same as the test class, but with an "inc" file extension.

Tags
since
1.0.0

$fileExtension

The file extension of the test case file (without leading dot).

protected static string $fileExtension = 'inc'

This allows concrete test classes to overrule the default "inc" with, for instance, "js" or "css" when applicable.

Tags
since
1.0.0

$phpcsFile

The \PHP_CodeSniffer\Files\File object containing the parsed contents of the test case file.

protected static File $phpcsFile
Tags
since
1.0.0

$phpcsVersion

The PHPCS version the tests are being run on.

protected static string $phpcsVersion = '0'
Tags
since
1.0.0-alpha3

$selectedSniff

Set the name of a sniff to pass to PHPCS to limit the run (and force it to record errors).

protected static array<string|int, mixed> $selectedSniff = ['Dummy.Dummy.Dummy']

Normally, this propery won't need to be overloaded, but for utility methods which record violations and contain fixers, setting a dummy sniff name equal to the sniff name passed in the error code for addError()/addWarning() during the test, will allow for testing the recording of these violations, as well as testing the fixer.

Tags
since
1.0.0

$tabWidth

The tab width setting to use when tokenizing the file.

protected static int $tabWidth = 4

This allows for test case files to use a different tab width than the default.

Tags
since
1.0.0

Methods

expectPhpcsException()

Helper method to tell PHPUnit to expect a PHPCS Exception in a PHPUnit and PHPCS cross-version compatible manner.

public expectPhpcsException(string $msg[, string $type = 'runtime' ]) : void
Parameters
$msg : string

The expected exception message.

$type : string = 'runtime'

The PHPCS native exception type to expect. Either 'runtime' or 'tokenizer'. Defaults to 'runtime'.

Tags
since
1.0.0
Return values
void

getTargetToken()

Get the token pointer for a target token based on a specific comment.

public static getTargetToken(string $commentString, int|string|array<string|int, mixed> $tokenType[, string $tokenContent = null ]) : int

Note: the test delimiter comment MUST start with /* test to allow this function to distinguish between comments used in a test and test delimiters.

Parameters
$commentString : string

The complete delimiter comment to look for as a string. This string should include the comment opener and closer.

$tokenType : int|string|array<string|int, mixed>

The type of token(s) to look for.

$tokenContent : string = null

Optional. The token content for the target token.

Tags
since
1.0.0
since
1.0.0-alpha4

Will throw an exception whether the delimiter comment or the target token is not found.

since
1.0.0-alpha4

This method is now static, which allows for it to be used in "set up before class".

throws
TestMarkerNotFound

When the delimiter comment for the test was not found.

throws
TestTargetNotFound

When the target token cannot be found.

Return values
int

resetTestFile()

Clean up after finished test by resetting all static properties to their default values.

public static resetTestFile() : void

Note: This is a PHPUnit cross-version compatible TestCase::tearDownAfterClass() method.

Tags
since
1.0.0
afterClass
Return values
void

setUpTestFile()

Initialize PHPCS & tokenize the test case file.

public static setUpTestFile() : void

The test case file for a unit test class has to be in the same directory directory and use the same file name as the test class, using the .inc extension or be explicitly set using the UtilityMethodTestCase::$fileExtension/ UtilityMethodTestCase::$caseFile properties.

Note: This is a PHPUnit cross-version compatible TestCase::setUpBeforeClass() method.

Tags
since
1.0.0
beforeClass
Return values
void

skipJSCSSTestsOnPHPCS4()

Skip JS and CSS related tests on PHPCS 4.x.

public skipJSCSSTestsOnPHPCS4() : void

PHPCS 4.x drops support for the JS and CSS tokenizers. This method takes care of automatically skipping tests involving JS/CSS case files when the tests are being run with PHPCS 4.x.

Note: This is a PHPUnit cross-version compatible TestCase::setUp() method.

Tags
since
1.0.0-alpha3
before
Return values
void

usesPhp8NameTokens()

Check whether or not the PHP 8.0 identifier name tokens will be in use.

public static usesPhp8NameTokens() : bool

The expected token positions/token counts for certain tokens will differ depending on whether the PHP 8.0 identifier name tokenization is used or the PHP < 8.0 identifier name tokenization.

Tests can use this method to determine which flavour of tokenization to expect and to set test expectations accordingly.

Tags
since
1.0.0
Return values
bool

Search results