WordPress.org

Make WordPress Core


Ignore:
Timestamp:
09/21/2021 11:02:13 PM (4 months ago)
Author:
hellofromTonya
Message:

Build/Test Tools: Introduce the PHPUnit Polyfills package for easier cross branch testing.

This backports the PHPUnit Polyfills package and related test infrastructure changes to make it easier for developers to continue testing on multiple versions WordPress while adding tests for newer versions of PHP, which require more modern PHPUnit practices.

One of the changes included is the addition of wrappers for the new snake_case fixture methods in PHPUnit. This allows the native camelCase standard in PHPUnit to be used, but allows for developers to transition to the new naming conventions.

Props hellofromTonya, jrf, SergeyBiryukov, johnbillion, netweb, schlessera, jeherve, lucatume, desrosj.
Merges [51559,51560,51810-51813,51828] to the 5.4 branch.
See #53911.

Location:
branches/5.4
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • branches/5.4

  • branches/5.4/tests/phpunit/includes/bootstrap.php

    r47328 r51844  
    5151    exit( 1 );
    5252}
     53
     54/*
     55 * Load the PHPUnit Polyfills autoloader.
     56 *
     57 * The PHPUnit Polyfills are a requirement for the WP test suite.
     58 *
     59 * For running the Core tests, the Make WordPress Core handbook contains step-by-step instructions
     60 * on how to get up and running for a variety of supported workflows:
     61 * {@link https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/#test-running-workflow-options}
     62 *
     63 * Plugin/theme integration tests can handle this in any of the following ways:
     64 * - When using a full WP install: run `composer install` for the WP install prior to running the tests.
     65 * - When using a partial WP test suite install:
     66 *   - Add a `yoast/phpunit-polyfills` (dev) requirement to the plugin/theme's own `composer.json` file.
     67 *   - And then:
     68 *     - Either load the PHPUnit Polyfills autoload file prior to running the WP core bootstrap file.
     69 *     - Or declare a `WP_TESTS_PHPUNIT_POLYFILLS_PATH` constant containing the absolute path to the
     70 *       root directory of the PHPUnit Polyfills installation.
     71 *       If the constant is used, it is strongly recommended to declare this constant in the plugin/theme's
     72 *       own test bootstrap file.
     73 *       The constant MUST be declared prior to calling this file.
     74 */
     75if ( ! class_exists( 'Yoast\PHPUnitPolyfills\Autoload' ) ) {
     76    // Default location of the autoloader for WP core test runs.
     77    $phpunit_polyfills_autoloader = dirname( dirname( dirname( __DIR__ ) ) ) . '/vendor/yoast/phpunit-polyfills/phpunitpolyfills-autoload.php';
     78    $phpunit_polyfills_error      = false;
     79
     80    // Allow for a custom installation location to be provided for plugin/theme integration tests.
     81    if ( defined( 'WP_TESTS_PHPUNIT_POLYFILLS_PATH' ) ) {
     82        $phpunit_polyfills_path = WP_TESTS_PHPUNIT_POLYFILLS_PATH;
     83
     84        if ( is_string( WP_TESTS_PHPUNIT_POLYFILLS_PATH )
     85            && '' !== WP_TESTS_PHPUNIT_POLYFILLS_PATH
     86        ) {
     87            // Be tolerant to the path being provided including the filename.
     88            if ( substr( $phpunit_polyfills_path, -29 ) !== 'phpunitpolyfills-autoload.php' ) {
     89                $phpunit_polyfills_path = rtrim( $phpunit_polyfills_path, '/\\' );
     90                $phpunit_polyfills_path = $phpunit_polyfills_path . '/phpunitpolyfills-autoload.php';
     91            }
     92
     93            $phpunit_polyfills_autoloader = $phpunit_polyfills_path;
     94        } else {
     95            $phpunit_polyfills_error = true;
     96        }
     97    }
     98
     99    if ( $phpunit_polyfills_error || ! file_exists( $phpunit_polyfills_autoloader ) ) {
     100        echo 'Error: The PHPUnit Polyfills library is a requirement for running the WP test suite.' . PHP_EOL;
     101        if ( defined( 'WP_TESTS_PHPUNIT_POLYFILLS_PATH' ) ) {
     102            printf(
     103                'The PHPUnit Polyfills autoload file was not found in "%s"' . PHP_EOL,
     104                WP_TESTS_PHPUNIT_POLYFILLS_PATH
     105            );
     106            echo 'Please verify that the file path provided in the WP_TESTS_PHPUNIT_POLYFILLS_PATH constant is correct.' . PHP_EOL;
     107            echo 'The WP_TESTS_PHPUNIT_POLYFILLS_PATH constant should contain an absolute path to the root directory'
     108                . ' of the PHPUnit Polyfills library.' . PHP_EOL;
     109        } elseif ( defined( 'WP_RUN_CORE_TESTS' ) && WP_RUN_CORE_TESTS ) {
     110            echo 'You need to run `composer install` before running the tests.' . PHP_EOL;
     111            echo 'Once the dependencies are installed, you can run the tests using the Composer-installed version'
     112                . ' of PHPUnit or using a PHPUnit phar file, but the dependencies do need to be installed'
     113                . ' whichever way the tests are run.' . PHP_EOL;
     114        } else {
     115            echo 'If you are trying to run plugin/theme integration tests, make sure the PHPUnit Polyfills library'
     116                . ' (https://github.com/Yoast/PHPUnit-Polyfills) is available and either load the autoload file'
     117                . ' of this library in your own test bootstrap before calling the WP Core test bootstrap file;'
     118                . ' or set the absolute path to the PHPUnit Polyfills library in a "WP_TESTS_PHPUNIT_POLYFILLS_PATH"'
     119                . ' constant to allow the WP Core bootstrap to load the Polyfills.' . PHP_EOL . PHP_EOL;
     120            echo 'If you are trying to run the WP Core tests, make sure to set the "WP_RUN_CORE_TESTS" constant'
     121                . ' to 1 and run `composer install` before running the tests.' . PHP_EOL;
     122            echo 'Once the dependencies are installed, you can run the tests using the Composer-installed'
     123                . ' version of PHPUnit or using a PHPUnit phar file, but the dependencies do need to be'
     124                . ' installed whichever way the tests are run.' . PHP_EOL;
     125        }
     126        exit( 1 );
     127    }
     128
     129    require_once $phpunit_polyfills_autoloader;
     130}
     131unset( $phpunit_polyfills_autoloader, $phpunit_polyfills_error, $phpunit_polyfills_path );
     132
     133/*
     134 * Minimum version of the PHPUnit Polyfills package as declared in `composer.json`.
     135 * Only needs updating when new polyfill features start being used in the test suite.
     136 */
     137$phpunit_polyfills_minimum_version = '1.0.1';
     138if ( class_exists( '\Yoast\PHPUnitPolyfills\Autoload' )
     139    && ( defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) === false
     140        || version_compare( Yoast\PHPUnitPolyfills\Autoload::VERSION, $phpunit_polyfills_minimum_version, '<' ) )
     141) {
     142    printf(
     143        'Error: Version mismatch detected for the PHPUnit Polyfills.'
     144        . ' Please ensure that PHPUnit Polyfills %s or higher is loaded. Found version: %s' . PHP_EOL,
     145        $phpunit_polyfills_minimum_version,
     146        defined( '\Yoast\PHPUnitPolyfills\Autoload::VERSION' ) ? Yoast\PHPUnitPolyfills\Autoload::VERSION : '1.0.0 or lower'
     147    );
     148    if ( defined( 'WP_TESTS_PHPUNIT_POLYFILLS_PATH' ) ) {
     149        printf(
     150            'Please ensure that the PHPUnit Polyfill installation in "%s" is updated to version %s or higher.' . PHP_EOL,
     151            WP_TESTS_PHPUNIT_POLYFILLS_PATH,
     152            $phpunit_polyfills_minimum_version
     153        );
     154    } elseif ( defined( 'WP_RUN_CORE_TESTS' ) && WP_RUN_CORE_TESTS ) {
     155        echo 'Please run `composer install` to install the latest version.' . PHP_EOL;
     156    }
     157    exit( 1 );
     158}
     159unset( $phpunit_polyfills_minimum_version );
    53160
    54161tests_reset__SERVER();
Note: See TracChangeset for help on using the changeset viewer.