PHPCSUtils

UtilityMethodTestCase extends TestCase

Base class for use when testing utility methods for PHP_CodeSniffer.

This class is compatible with PHP_CodeSniffer 2.x as well as 3.x.

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 \PHPCSUtils\TestUtils\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

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
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.
setUpTestFile()  : void
Initialize PHPCS & tokenize the test case file.
skipJSCSSTestsOnPHPCS4()  : void
Skip JS and CSS related tests on PHPCS 4.x.

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 $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

getTargetToken()

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

public getTargetToken(string $commentString, int|string|array $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.

If the delimiter comment is not found, the test will automatically be failed.

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

The type of token(s) to look for.

$tokenContent : string = null

Optional. The token content for the target token.

Tags
since
1.0.0
Return values
int

resetTestFile()

Clean up after finished test.

public static resetTestFile() : void

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

Tags
since
1.0.0
afterClass

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 \PHPCSUtils\TestUtils\UtilityMethodTestCase::$fileExtension/ \PHPCSUtils\TestUtils\UtilityMethodTestCase::$caseFile properties.

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

Tags
since
1.0.0
beforeClass

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 \PHPUnit\Framework\TestCase::setUp() method.

Tags
since
1.0.0-alpha3
before

Search results