Documentation

IsUnitTestTrait

Helper utilities for sniffs which need to take into account whether the code under examination is unit test code or not.

Usage instructions:

  • Add appropriate use statement(s) to the file/class which intends to use this functionality.
  • Now the sniff will automatically support the public custom_test_classes property which users can set in their custom ruleset. Do not add the property to the sniff!
  • The sniff can call the is_test_class() method in this trait to verify if a class is a test class. The is_test_class() method will take the custom property into account.
Tags
since
3.0.0

The properties and method in this trait were previously contained in the WordPressCS\WordPress\Sniff class and have been moved here.

Table of Contents

Properties

$custom_test_classes  : array<string|int, string>
Custom list of classes which test classes can extend.
$added_custom_test_classes  : array<string|int, string>
Cache of previously added custom test classes.
$all_test_classes  : array<string, bool>
Combined list of WP/PHPUnit native and custom test classes.
$known_test_classes  : array<string, true>
List of PHPUnit and WP native classes which test classes can extend.

Methods

get_all_test_classes()  : array<string, bool>
Retrieve a list of all registered test classes, both WP/PHPUnit native as well as custom.
is_test_class()  : bool
Check if a class token is part of a unit test suite.

Properties

$custom_test_classes

Custom list of classes which test classes can extend.

public array<string|int, string> $custom_test_classes = array()

This property allows end-users to add to the build-in $known_test_classes via their custom PHPCS ruleset. This property will need to be set for each sniff which uses this trait.

Currently this property is used by the WordPress.WP.GlobalVariablesOverride, WordPress.NamingConventions.PrefixAllGlobals and the WordPress.Files.Filename sniffs.

Example usage:

<rule ref="WordPress.[Subset].[Sniffname]">
 <properties>
  <property name="custom_test_classes" type="array">
    <element value="My_Plugin_First_Test_Class"/>
    <element value="My_Plugin_Second_Test_Class"/>
  </property>
 </properties>
</rule>

Note: it is strongly recommended to exclude your test directories for select error codes of those particular sniffs instead of relying on this property/trait.

Tags
since
0.11.0
since
3.0.0

Moved from the Sniff class to this dedicated Trait. Renamed from $custom_test_class_whitelist to $custom_test_classes.

used-by
FileNameSniff
used-by
PrefixAllGlobalsSniff
used-by
GlobalVariablesOverrideSniff

$added_custom_test_classes

Cache of previously added custom test classes.

private array<string|int, string> $added_custom_test_classes = array()

Prevents having to do the same merges over and over again.

Tags
since
3.0.0

$all_test_classes

Combined list of WP/PHPUnit native and custom test classes.

private array<string, bool> $all_test_classes = array()
Tags
since
3.0.0

$known_test_classes

List of PHPUnit and WP native classes which test classes can extend.

private array<string, true> $known_test_classes = array( // Base test cases. 'WP_UnitTestCase' => true, 'WP_UnitTestCase_Base' => true, 'PHPUnit_Adapter_TestCase' => true, // Domain specific base test cases. 'WP_Ajax_UnitTestCase' => true, 'WP_Canonical_UnitTestCase' => true, 'WP_Font_Face_UnitTestCase' => true, 'WP_Test_REST_Controller_Testcase' => true, 'WP_Test_REST_Post_Type_Controller_Testcase' => true, 'WP_Test_REST_TestCase' => true, 'WP_Test_XML_TestCase' => true, 'WP_XMLRPC_UnitTestCase' => true, // PHPUnit native test cases. 'PHPUnit_Framework_TestCase' => true, 'PHPUnit\Framework\TestCase' => true, // PHPUnit native TestCase class when imported via use statement. 'TestCase' => true, )

{internal These are the test cases provided in the /tests/phpunit/includes/ directory of WP Core.}

Key is class name, value irrelevant.

Tags
since
0.11.0
since
3.0.0
  • Moved from the Sniff class to this dedicated Trait.
  • Renamed from $test_class_whitelist to $known_test_classes.
  • Visibility changed from protected to private.

Methods

get_all_test_classes()

Retrieve a list of all registered test classes, both WP/PHPUnit native as well as custom.

protected final get_all_test_classes() : array<string, bool>
Tags
since
3.0.0
Return values
array<string, bool>

is_test_class()

Check if a class token is part of a unit test suite.

protected final is_test_class(File $phpcsFile, int $stackPtr) : bool

Unit test classes are identified as such:

  • Class which either extends one of the known test cases, such as WP_UnitTestCase or PHPUnit_Framework_TestCase or extends a custom unit test class as listed in the custom_test_classes property.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the token to be examined. This should be a class, anonymous class or trait token.

Tags
since
0.12.0

Split off from the is_token_in_test_method() method.

since
1.0.0

Improved recognition of namespaced class names.

since
3.0.0
  • Moved from the Sniff class to this dedicated Trait.
  • The $phpcsFile parameter was added.
Return values
bool —

True if the class is a unit test class, false otherwise.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results