From 3a7ff0e2e64abe599bc9b1936e534b43aecc3736 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 8 Dec 2017 21:00:08 +0000 Subject: [PATCH] Build/Test tools: Add inline documentation to undocumented methods in the `WP_UnitTestCase` class. Props Frank Klein Fixes #42731 git-svn-id: https://develop.svn.wordpress.org/trunk@42379 602fd350-edb4-49c9-b593-d223f7449a82 --- tests/phpunit/includes/testcase.php | 193 +++++++++++++++++++++++++--- 1 file changed, 177 insertions(+), 16 deletions(-) diff --git a/tests/phpunit/includes/testcase.php b/tests/phpunit/includes/testcase.php index c5797f6798..fee06e0df9 100644 --- a/tests/phpunit/includes/testcase.php +++ b/tests/phpunit/includes/testcase.php @@ -519,12 +519,28 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { $this->assertEquals( preg_replace( '/\s*/', '', $expected ), preg_replace( '/\s*/', '', $actual ) ); } + /** + * Asserts that the contents of two un-keyed, single arrays are equal, without accounting for the order of elements. + * + * @since 3.5.0 + * + * @param array $expected Expected array. + * @param array $actual Array to check. + */ function assertEqualSets( $expected, $actual ) { sort( $expected ); sort( $actual ); $this->assertEquals( $expected, $actual ); } + /** + * Asserts that the contents of two keyed, single arrays are equal, without accounting for the order of elements. + * + * @since 4.1.0 + * + * @param array $expected Expected array. + * @param array $actual Array to check. + */ function assertEqualSetsWithIndex( $expected, $actual ) { ksort( $expected ); ksort( $actual ); @@ -534,7 +550,9 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { /** * Asserts that the given variable is a multidimensional array, and that all arrays are non-empty. * - * @param array $array + * @since 4.8.0 + * + * @param array $array Array to check. */ function assertNonEmptyMultidimensionalArray( $array ) { $this->assertTrue( is_array( $array ) ); @@ -549,8 +567,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { /** * Asserts that a condition is not false. * - * @param bool $condition - * @param string $message + * This method has been backported from a more recent PHPUnit version, as tests running on PHP 5.2 use + * PHPUnit 3.6.x. + * + * @since 4.7.4 + * + * @param bool $condition Condition to check. + * @param string $message Optional. Message to display when the assertion fails. * * @throws PHPUnit_Framework_AssertionFailedError */ @@ -559,7 +582,15 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Modify WordPress's query internals as if a given URL has been requested. + * Sets the global state to as if a given URL has been requested. + * + * This sets: + * - The super globals. + * - The globals. + * - The query variables. + * - The main query. + * + * @since 3.5.0 * * @param string $url The URL for the request. */ @@ -608,6 +639,16 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { $GLOBALS['wp']->main( $parts['query'] ); } + /** + * Allows tests to be skipped on single or multisite installs by using @group annotations. + * + * This is a custom extension of the PHPUnit requirements handling. + * + * Contains legacy code for skipping tests that are associated with an open Trac ticket. Core tests no longer + * support this behaviour. + * + * @since 3.5.0 + */ protected function checkRequirements() { parent::checkRequirements(); @@ -644,7 +685,11 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Skips the current test if there is an open WordPress ticket with id $ticket_id + * Skips the current test if there is an open Trac ticket associated with it. + * + * @since 3.5.0 + * + * @param int $ticket_id Ticket number. */ function knownWPBug( $ticket_id ) { if ( WP_TESTS_FORCE_KNOWN_BUGS || in_array( $ticket_id, self::$forced_tickets ) ) { @@ -656,14 +701,24 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * @deprecated No longer used since the unit test Trac was merged into Core's. + * Skips the current test if there is an open Unit Test Trac ticket associated with it. + * + * @since 3.5.0 + * + * @deprecated No longer used since the Unit Test Trac was merged into the Core Trac. + * + * @param int $ticket_id Ticket number. */ function knownUTBug( $ticket_id ) { return; } /** - * Skips the current test if there is an open plugin ticket with id $ticket_id + * Skips the current test if there is an open Plugin Trac ticket associated with it. + * + * @since 3.5.0 + * + * @param int $ticket_id Ticket number. */ function knownPluginBug( $ticket_id ) { if ( WP_TESTS_FORCE_KNOWN_BUGS || in_array( 'Plugin' . $ticket_id, self::$forced_tickets ) ) { @@ -674,12 +729,26 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } } + /** + * Adds a Trac ticket number to the `$forced_tickets` property. + * + * @since 3.5.0 + * + * @param int $ticket Ticket number. + */ public static function forceTicket( $ticket ) { self::$forced_tickets[] = $ticket; } /** - * Define constants after including files. + * Custom preparations for the PHPUnit process isolation template. + * + * When restoring global state between tests, PHPUnit defines all the constants that were already defined, and then + * includes included files. This does not work with WordPress, as the included files define the constants. + * + * This method defines the constants after including files. + * + * @param Text_Template $template */ function prepareTemplate( Text_Template $template ) { $template->setVar( array( 'constants' => '' ) ); @@ -688,7 +757,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Returns the name of a temporary file + * Creates a unique temporary file name. + * + * The directory in which the file is created depends on the environment configuration. + * + * @since 3.5.0 + * + * @return string|bool Path on success, else false. */ function temp_filename() { $tmp_dir = ''; @@ -707,12 +782,15 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Check each of the WP_Query is_* functions/properties against expected boolean value. + * Checks each of the WP_Query is_* functions/properties against expected boolean value. * * Any properties that are listed by name as parameters will be expected to be true; all others are * expected to be false. For example, assertQueryTrue('is_single', 'is_feed') means is_single() * and is_feed() must be true and everything else must be false to pass. * + * @since 2.5.0 + * @since 3.8.0 Moved from `Tests_Query_Conditionals` to `WP_UnitTestCase`. + * * @param string $prop,... Any number of WP_Query properties that are expected to be true for the current request. */ function assertQueryTrue() { @@ -775,6 +853,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } } + /** + * Selectively deletes a file. + * + * Does not delete a file if its path is set in the `$ignore_files` property. + * + * @param string $file File path. + */ function unlink( $file ) { $exists = is_file( $file ); if ( $exists && ! in_array( $file, self::$ignore_files ) ) { @@ -785,6 +870,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } } + /** + * Selectively deletes files from a directory. + * + * Does not delete files if their paths are set in the `$ignore_files` property. + * + * @param string $path Directory path. + */ function rmdir( $path ) { $files = $this->files_in_dir( $path ); foreach ( $files as $file ) { @@ -794,12 +886,29 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } } + /** + * Deletes files added to the `uploads` directory during tests. + * + * This method works in tandem with the `setUp()` and `rmdir()` methods: + * - `setUp()` scans the `uploads` directory before every test, and stores its contents inside of the + * `$ignore_files` property. + * - `rmdir()` and its helper methods only delete files that are not listed in the `$ignore_files` property. If + * called during `tearDown()` in tests, this will only delete files added during the previously run test. + */ function remove_added_uploads() { - // Remove all uploads. $uploads = wp_upload_dir(); $this->rmdir( $uploads['basedir'] ); } + /** + * Returns a list of all files contained inside a directory. + * + * @since 4.0.0 + * + * @param string $dir Path to the directory to scan. + * + * @return array List of file paths. + */ function files_in_dir( $dir ) { $files = array(); @@ -814,6 +923,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { return $files; } + /** + * Returns a list of all files contained inside the `uploads` directory. + * + * @since 4.0.0 + * + * @return array List of file paths. + */ function scan_user_uploads() { static $files = array(); if ( ! empty( $files ) ) { @@ -825,6 +941,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { return $files; } + /** + * Deletes all directories contained inside a directory. + * + * @since 4.1.0 + * + * @param string $path Path to the directory to scan. + */ function delete_folders( $path ) { $this->matched_dirs = array(); if ( ! is_dir( $path ) ) { @@ -838,6 +961,16 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { rmdir( $path ); } + /** + * Retrieves all directories contained inside a directory and stores them in the `$matched_dirs` property. Hidden + * directories are ignored. + * + * This is a helper for the `delete_folders()` method. + * + * @since 4.1.0 + * + * @param string $dir Path to the directory to scan. + */ function scandir( $dir ) { foreach ( scandir( $dir ) as $path ) { if ( 0 !== strpos( $path, '.' ) && is_dir( $dir . '/' . $path ) ) { @@ -848,7 +981,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Helper to Convert a microtime string into a float + * Converts a microtime string into a float. + * + * @since 4.1.0 + * + * @param string $microtime Time string generated by `microtime()`. + * + * @return float `microtime()` output as a float. */ protected function _microtime_to_float( $microtime ) { $time_array = explode( ' ', $microtime ); @@ -856,9 +995,13 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Multisite-agnostic way to delete a user from the database. + * Deletes a user from the database in a Multisite-agnostic way. * * @since 4.3.0 + * + * @param int $user_id User ID. + * + * @return bool True if the user was deleted. */ public static function delete_user( $user_id ) { if ( is_multisite() ) { @@ -869,7 +1012,7 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * Utility method that resets permalinks and flushes rewrites. + * Resets permalinks and flushes rewrites. * * @since 4.4.0 * @@ -885,6 +1028,16 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { $wp_rewrite->flush_rules(); } + /** + * Creates an attachment post from an uploaded file. + * + * @since 4.4.0 + * + * @param array $upload Array of information about the uploaded file, provided by wp_upload_bits(). + * @param int $parent_post_id Optional. Parent post ID. + * + * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure. + */ function _make_attachment( $upload, $parent_post_id = 0 ) { $type = ''; if ( ! empty( $upload['type'] ) ) { @@ -905,14 +1058,22 @@ class WP_UnitTestCase extends PHPUnit_Framework_TestCase { 'guid' => $upload['url'], ); - // Save the data $id = wp_insert_attachment( $attachment, $upload['file'], $parent_post_id ); wp_update_attachment_metadata( $id, wp_generate_attachment_metadata( $id, $upload['file'] ) ); return $id; } /** - * There's no way to change post_modified through WP functions. + * Updates the modified and modified GMT date of a post in the database. + * + * @since 4.8.0 + * + * @global wpdb $wpdb WordPress database abstraction object. + * + * @param int $post_id Post ID. + * @param string $date Post date, in the format YYYY-MM-DD HH:MM:SS. + * + * @return int|false 1 on success, or false on error. */ protected function update_post_modified( $post_id, $date ) { global $wpdb;