PHPCSUtils 1.0.12

UtilityMethodTestCase extends TestCase
in package

AbstractYes

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

Table of Contents

Properties

$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|null
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, string>
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.

Methods

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.
setStaticConfigProperty()  : void
Helper function to set the value of a private static property on the PHPCS Config class.
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|null $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

$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, string> $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 static getTargetToken(string $commentString, int|string|array<string|int, int|string> $tokenType[, string|null $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, int|string>

The type of token(s) to look for.

$tokenContent : string|null = null

Optional. The token content for the target token.

Tags
since
1.0.0
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

setStaticConfigProperty()

Helper function to set the value of a private static property on the PHPCS Config class.

public static setStaticConfigProperty(string $name, mixed $value) : void
Parameters
$name : string

The name of the property to set.

$value : mixed

The value to set the property to.

Tags
since
1.0.9

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

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
before

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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results