sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Build/Test tools: Add inline documentation to undocumented methods in the WP_UnitTestCase class.

Browse Source 
Props Frank Klein

Fixes #42731


git-svn-id: https://develop.svn.wordpress.org/trunk@42379 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
John Blackbourn 2017-12-08 21:00:08 +00:00
parent 72b74509f3
commit 3a7ff0e2e6
1 changed files with 177 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
tests/phpunit/includes/testcase.php
View File

@ -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;