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

@@ -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
+	 * This method has been backported from a more recent PHPUnit version, as tests running on PHP 5.2 use
-	 * @param string $message
+	 * 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;