diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory.php b/tests/phpunit/includes/factory/class-wp-unittest-factory.php index 3b74092e62..4d0934bb9a 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory.php @@ -8,52 +8,72 @@ class WP_UnitTest_Factory { /** + * Generates post fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_Post */ public $post; /** + * Generates attachment fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_Attachment */ public $attachment; /** + * Generates comment fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_Comment */ public $comment; /** + * Generates user fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_User */ public $user; /** + * Generates taxonomy term fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_Term */ public $term; /** + * Generates category fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_Term */ public $category; /** + * Generates tag fixtures for use in tests. + * * @var WP_UnitTest_Factory_For_Term */ public $tag; /** + * Generates bookmark (link) fixtures for use in tests. + * * @since 4.6.0 * @var WP_UnitTest_Factory_For_Bookmark */ public $bookmark; /** + * Generates blog (site) fixtures for use in Multisite tests. + * * @var WP_UnitTest_Factory_For_Blog */ public $blog; /** + * Generates network fixtures for use in Multisite tests. + * * @var WP_UnitTest_Factory_For_Network */ public $network; diff --git a/tests/phpunit/includes/mock-mailer.php b/tests/phpunit/includes/mock-mailer.php index d02d2efc69..ee04ce0627 100644 --- a/tests/phpunit/includes/mock-mailer.php +++ b/tests/phpunit/includes/mock-mailer.php @@ -76,7 +76,7 @@ class MockPHPMailer extends PHPMailer\PHPMailer\PHPMailer { * * @since 4.4.0 * - * @return object|bool + * @return MockPHPMailer|false */ function tests_retrieve_phpmailer_instance() { $mailer = false; diff --git a/tests/phpunit/includes/utils.php b/tests/phpunit/includes/utils.php index b178418de7..7a0de67377 100644 --- a/tests/phpunit/includes/utils.php +++ b/tests/phpunit/includes/utils.php @@ -2,10 +2,23 @@ // Misc help functions and utilities. +/** + * Returns a string of the required length containing random characters. Note that + * the maximum possible string length is 32. + * + * @param int $len Optional. The required length. Default 32. + * @return string The string. + */ function rand_str( $len = 32 ) { return substr( md5( uniqid( rand() ) ), 0, $len ); } +/** + * Returns a string of the required length containing random characters. + * + * @param int $len The required length. + * @return string The string. + */ function rand_long_str( $length ) { $chars = 'abcdefghijklmnopqrstuvwxyz'; $string = ''; @@ -18,7 +31,12 @@ function rand_long_str( $length ) { return $string; } -// Strip leading and trailing whitespace from each line in the string. +/** + * Strips leading and trailing whitespace from each line in the string. + * + * @param string $txt The text. + * @return string Text with line-leading and line-trailing whitespace stripped. + */ function strip_ws( $txt ) { $lines = explode( "\n", $txt ); $result = array(); @@ -33,9 +51,11 @@ function strip_ws( $txt ) { /* * Helper class for testing code that involves actions and filters. + * * Typical use: - * $ma = new MockAction(); - * add_action( 'foo', array( &$ma, 'action' ) ); + * + * $ma = new MockAction(); + * add_action( 'foo', array( &$ma, 'action' ) ); */ class MockAction { public $events; @@ -240,11 +260,31 @@ class TestXMLParser { } } +/** + * Converts an XML string into an array tree structure. + * + * The output of this function can be passed to xml_find() to find nodes by their path. + * + * @param string $in The XML string. + * @return array XML as an array. + */ function xml_to_array( $in ) { $p = new TestXMLParser( $in ); return $p->data; } +/** + * Finds XML nodes by a given "path". + * + * Example usage: + * + * $tree = xml_to_array( $rss ); + * $items = xml_find( $tree, 'rss', 'channel', 'item' ); + * + * @param array $tree An array tree structure of XML, typically from xml_to_array(). + * @param string ...$elements Names of XML nodes to create a "path" to find within the XML. + * @return array Array of matching XML node information. + */ function xml_find( $tree, ...$elements ) { $n = count( $elements ); $out = array();