Ticket #42731: 42731-1.patch

tests/phpunit/includes/testcase.php

@@ -513 +513 @@
                 $this->assertEquals( preg_replace( '/\s*/', '', $expected ), preg_replace( '/\s*/', '', $actual ) );
         }
 
+        /**
+         * Assert 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 );
         }
 
+        /**
+         * Assert 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 );
@@ -526 +542 @@
         }
 
         /**
-         * Asserts that the given variable is a multidimensional array, and that all arrays are non-empty.
+         * Assert 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 ) );
@@ -541 +559 @@
         }
 
         /**
-         * Asserts that a condition is not false.
+         * Assert that a condition is not false.
+         *
+         * This method has been back ported from a more recent PHPUnit version, as tests running on PHP 5.2 use
+         * PHPUnit 3.6.x.
          *
-         * @param bool   $condition
-         * @param string $message
+         * @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
          */
@@ -553 +576 @@
         }
 
         /**
-         * Modify WordPress's query internals as if a given URL has been requested.
+         * Set 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.
          */
@@ -600 +631 @@
                 $GLOBALS['wp']->main($parts['query']);
         }
 
+        /**
+         * Custom extension of the PHPUnit requirements handling.
+         *
+         * Allows tests to be skipped on single or multisite installs by using @group annotations.
+         *
+         * Contains legacy code for skipping tests that are associated with an open Trac ticket. Core tests do no longer
+         * support this behaviour.
+         *
+         * @since 3.5.0
+         */
         protected function checkRequirements() {
                 parent::checkRequirements();
 
@@ -634 +675 @@
         }
 
         /**
-         * 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 ) )
@@ -644 +689 @@
         }
 
         /**
-         * @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 ) )
@@ -660 +715 @@
                         $this->markTestSkipped( sprintf( 'WordPress Plugin Ticket #%d is not fixed', $ticket_id ) );
         }
 
+        /**
+         * Add 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' => '' ) );
@@ -674 +743 @@
         }
 
         /**
-         * Returns the name of a temporary file
+         * Create 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 = '';
@@ -698 +773 @@
          * 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(/* ... */) {
@@ -760 +838 @@
                 }
         }
 
+        /**
+         * Helper to selectively delete 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 ) ) {
-                        //error_log( $file );
                         unlink( $file );
                 } elseif ( ! $exists ) {
                         $this->fail( "Trying to delete a file that doesn't exist: $file" );
                 }
         }
 
+        /**
+         * Helper to selectively delete 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 ) {
@@ -779 +870 @@
                 }
         }
 
+        /**
+         * Helper to delete 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'] );
         }
 
+        /**
+         * Return 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();
 
@@ -799 +907 @@
                 return $files;
         }
 
+        /**
+         * Return 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 ) ) {
@@ -810 +925 @@
                 return $files;
         }
 
+        /**
+         * Delete 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 ) ) {
@@ -823 +945 @@
                 rmdir( $path );
         }
 
+        /**
+         * Helper for `delete_folders()` method.
+         *
+         * Retrieves all directories contained inside a directory and stores them in the `$matched_dirs` property. Hidden
+         * directories are ignored.
+         *
+         * @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 ) ) {
@@ -833 +965 @@
         }
 
         /**
-         * Helper to Convert a microtime string into a float
+         * Helper to convert 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 );
@@ -844 +982 @@
          * Multisite-agnostic way to delete a user from the database.
          *
          * @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() ) {
@@ -870 +1012 @@
                 $wp_rewrite->flush_rules();
         }
 
+        /**
+         * Create 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']) ) {
@@ -889 +1041 @@
                         '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.
+         * Update 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;