Tests: Update the terminology used for action or filter names in MockAction class.

This replaces the "tag" wording with "hook name" where appropriate, to match the core function signatures.

Includes:
* Introducing a `::get_hook_names()` method instead of `::get_tags()`, keeping the latter as an alias.
* Adding a `hook_name` key to the `::$events` property, keeping `tag` for backward compatibility for now.
* Adding missing `@since` tags for class methods.

Follow-up to [24/tests], [62/tests], [70/tests], [50807], [53804].

See #55652.

git-svn-id: https://develop.svn.wordpress.org/trunk@53805 602fd350-edb4-49c9-b593-d223f7449a82

tests/phpunit/includes/utils.php

@@ -56,6 +56,8 @@ function strip_ws( $txt ) {
  *
  *     $ma = new MockAction();
  *     add_action( 'foo', array( &$ma, 'action' ) );
+ *
+ * @since UT (3.7.0)
  */
 class MockAction {
 	public $events;
@@ -63,140 +65,221 @@ class MockAction {
 
 	/**
 	 * PHP5 constructor.
+	 *
+	 * @since UT (3.7.0)
 	 */
 	public function __construct( $debug = 0 ) {
 		$this->reset();
 		$this->debug = $debug;
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function reset() {
 		$this->events = array();
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function current_filter() {
+		global $wp_actions;
+
 		if ( is_callable( 'current_filter' ) ) {
 			return current_filter();
 		}
-		global $wp_actions;
+
 		return end( $wp_actions );
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function action( $arg ) {
+		$current_filter = $this->current_filter();
+
 		if ( $this->debug ) {
-			dmp( __FUNCTION__, $this->current_filter() );
+			dmp( __FUNCTION__, $current_filter );
 		}
-		$args           = func_get_args();
+
 		$this->events[] = array(
-			'action' => __FUNCTION__,
-			'tag'    => $this->current_filter(),
-			'args'   => $args,
+			'action'    => __FUNCTION__,
+			'hook_name' => $current_filter,
+			'tag'       => $current_filter, // Back compat.
+			'args'      => func_get_args(),
 		);
+
 		return $arg;
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function action2( $arg ) {
+		$current_filter = $this->current_filter();
+
 		if ( $this->debug ) {
-			dmp( __FUNCTION__, $this->current_filter() );
+			dmp( __FUNCTION__, $current_filter );
 		}
 
-		$args           = func_get_args();
 		$this->events[] = array(
-			'action' => __FUNCTION__,
-			'tag'    => $this->current_filter(),
-			'args'   => $args,
+			'action'    => __FUNCTION__,
+			'hook_name' => $current_filter,
+			'tag'       => $current_filter, // Back compat.
+			'args'      => func_get_args(),
 		);
+
 		return $arg;
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function filter( $arg ) {
+		$current_filter = $this->current_filter();
+
 		if ( $this->debug ) {
-			dmp( __FUNCTION__, $this->current_filter() );
+			dmp( __FUNCTION__, $current_filter );
 		}
 
-		$args           = func_get_args();
 		$this->events[] = array(
-			'filter' => __FUNCTION__,
-			'tag'    => $this->current_filter(),
-			'args'   => $args,
+			'filter'    => __FUNCTION__,
+			'hook_name' => $current_filter,
+			'tag'       => $current_filter, // Back compat.
+			'args'      => func_get_args(),
 		);
+
 		return $arg;
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function filter2( $arg ) {
+		$current_filter = $this->current_filter();
+
 		if ( $this->debug ) {
-			dmp( __FUNCTION__, $this->current_filter() );
+			dmp( __FUNCTION__, $current_filter );
 		}
 
-		$args           = func_get_args();
 		$this->events[] = array(
-			'filter' => __FUNCTION__,
-			'tag'    => $this->current_filter(),
-			'args'   => $args,
+			'filter'    => __FUNCTION__,
+			'hook_name' => $current_filter,
+			'tag'       => $current_filter, // Back compat.
+			'args'      => func_get_args(),
 		);
+
 		return $arg;
 	}
 
+	/**
+	 * @since UT (3.7.0)
+	 */
 	public function filter_append( $arg ) {
+		$current_filter = $this->current_filter();
+
 		if ( $this->debug ) {
-			dmp( __FUNCTION__, $this->current_filter() );
+			dmp( __FUNCTION__, $current_filter );
 		}
 
-		$args           = func_get_args();
 		$this->events[] = array(
-			'filter' => __FUNCTION__,
-			'tag'    => $this->current_filter(),
-			'args'   => $args,
+			'filter'    => __FUNCTION__,
+			'hook_name' => $current_filter,
+			'tag'       => $current_filter, // Back compat.
+			'args'      => func_get_args(),
 		);
+
 		return $arg . '_append';
 	}
 
-	public function filterall( $tag, ...$args ) {
-		// This one doesn't return the result, so it's safe to use with the new 'all' filter.
+	/**
+	 * Does not return the result, so it's safe to use with the 'all' filter.
+	 *
+	 * @since UT (3.7.0)
+	 */
+	public function filterall( $hook_name, ...$args ) {
+		$current_filter = $this->current_filter();
+
 		if ( $this->debug ) {
-			dmp( __FUNCTION__, $this->current_filter() );
+			dmp( __FUNCTION__, $current_filter );
 		}
 
 		$this->events[] = array(
-			'filter' => __FUNCTION__,
-			'tag'    => $tag,
-			'args'   => $args,
+			'filter'    => __FUNCTION__,
+			'hook_name' => $hook_name,
+			'tag'       => $hook_name, // Back compat.
+			'args'      => $args,
 		);
 	}
 
-	// Return a list of all the actions, tags and args.
+	/**
+	 * Returns a list of all the actions, hook names and args.
+	 *
+	 * @since UT (3.7.0)
+	 */
 	public function get_events() {
 		return $this->events;
 	}
 
-	// Return a count of the number of times the action was called since the last reset.
-	public function get_call_count( $tag = '' ) {
-		if ( $tag ) {
+	/**
+	 * Returns a count of the number of times the action was called since the last reset.
+	 *
+	 * @since UT (3.7.0)
+	 */
+	public function get_call_count( $hook_name = '' ) {
+		if ( $hook_name ) {
 			$count = 0;
+
 			foreach ( $this->events as $e ) {
-				if ( $e['action'] === $tag ) {
+				if ( $e['action'] === $hook_name ) {
 					++$count;
 				}
 			}
+
 			return $count;
 		}
+
 		return count( $this->events );
 	}
 
-	// Return an array of the tags that triggered calls to this action.
-	public function get_tags() {
+	/**
+	 * Returns an array of the hook names that triggered calls to this action.
+	 *
+	 * @since 6.1.0
+	 */
+	public function get_hook_names() {
 		$out = array();
+
 		foreach ( $this->events as $e ) {
-			$out[] = $e['tag'];
+			$out[] = $e['hook_name'];
 		}
+
 		return $out;
 	}
 
-	// Return an array of args passed in calls to this action.
+	/**
+	 * Returns an array of the hook names that triggered calls to this action.
+	 *
+	 * @since UT (3.7.0)
+	 * @since 6.1.0 Turned into an alias for ::get_hook_names().
+	 */
+	public function get_tags() {
+		return $this->get_hook_names();
+	}
+
+	/**
+	 * Returns an array of args passed in calls to this action.
+	 *
+	 * @since UT (3.7.0)
+	 */
 	public function get_args() {
 		$out = array();
+
 		foreach ( $this->events as $e ) {
 			$out[] = $e['args'];
 		}
+
 		return $out;
 	}
 }

tests/phpunit/tests/actions.php

@@ -20,7 +20,7 @@ class Tests_Actions extends WP_UnitTestCase {
 		// Only one event occurred for the hook, with empty args.
 		$this->assertSame( 1, $a->get_call_count() );
 		// Only our hook was called.
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 		$argsvar = $a->get_args();
 		$args    = array_pop( $argsvar );
@@ -39,13 +39,13 @@ class Tests_Actions extends WP_UnitTestCase {
 
 		// Make sure our hook was called correctly.
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 		// Now remove the action, do it again, and make sure it's not called this time.
 		remove_action( $hook_name, array( &$a, 'action' ) );
 		do_action( $hook_name );
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 	}
 
@@ -215,15 +215,17 @@ class Tests_Actions extends WP_UnitTestCase {
 		$expected = array(
 			// 'action2' is called first because it has priority 9.
 			array(
-				'action' => 'action2',
-				'tag'    => $hook_name,
-				'args'   => array( '' ),
+				'action'    => 'action2',
+				'hook_name' => $hook_name,
+				'tag'       => $hook_name, // Back compat.
+				'args'      => array( '' ),
 			),
 			// 'action' is called second.
 			array(
-				'action' => 'action',
-				'tag'    => $hook_name,
-				'args'   => array( '' ),
+				'action'    => 'action',
+				'hook_name' => $hook_name,
+				'tag'       => $hook_name, // Back compat.
+				'args'      => array( '' ),
 			),
 		);
 
@@ -274,7 +276,7 @@ class Tests_Actions extends WP_UnitTestCase {
 		// Our action should have been called once for each tag.
 		$this->assertSame( 4, $a->get_call_count() );
 		// Only our hook was called.
-		$this->assertSame( array( $hook_name1, $hook_name2, $hook_name1, $hook_name1 ), $a->get_tags() );
+		$this->assertSame( array( $hook_name1, $hook_name2, $hook_name1, $hook_name1 ), $a->get_hook_names() );
 
 		remove_action( 'all', array( &$a, 'action' ) );
 		$this->assertFalse( has_filter( 'all', array( &$a, 'action' ) ) );
@@ -294,14 +296,14 @@ class Tests_Actions extends WP_UnitTestCase {
 
 		// Make sure our hook was called correctly.
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 		// Now remove the action, do it again, and make sure it's not called this time.
 		remove_action( 'all', array( &$a, 'action' ) );
 		$this->assertFalse( has_filter( 'all', array( &$a, 'action' ) ) );
 		do_action( $hook_name );
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 	}
 
 	/**

tests/phpunit/tests/filters.php

@@ -18,7 +18,7 @@ class Tests_Filters extends WP_UnitTestCase {
 		// Only one event occurred for the hook, with empty args.
 		$this->assertSame( 1, $a->get_call_count() );
 		// Only our hook was called.
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 		$argsvar = $a->get_args();
 		$args    = array_pop( $argsvar );
@@ -35,13 +35,13 @@ class Tests_Filters extends WP_UnitTestCase {
 
 		// Make sure our hook was called correctly.
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 		// Now remove the filter, do it again, and make sure it's not called this time.
 		remove_filter( $hook_name, array( $a, 'filter' ) );
 		$this->assertSame( $val, apply_filters( $hook_name, $val ) );
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 	}
 
@@ -135,15 +135,17 @@ class Tests_Filters extends WP_UnitTestCase {
 		$expected = array(
 			// 'filter2' is called first because it has priority 9.
 			array(
-				'filter' => 'filter2',
-				'tag'    => $hook_name,
-				'args'   => array( $val ),
+				'filter'    => 'filter2',
+				'hook_name' => $hook_name,
+				'tag'       => $hook_name, // Back compat.
+				'args'      => array( $val ),
 			),
 			// 'filter' is called second.
 			array(
-				'filter' => 'filter',
-				'tag'    => $hook_name,
-				'args'   => array( $val ),
+				'filter'    => 'filter',
+				'hook_name' => $hook_name,
+				'tag'       => $hook_name, // Back compat.
+				'args'      => array( $val ),
 			),
 		);
 
@@ -192,7 +194,7 @@ class Tests_Filters extends WP_UnitTestCase {
 		// Our filter should have been called once for each apply_filters call.
 		$this->assertSame( 4, $a->get_call_count() );
 		// The right hooks should have been called in order.
-		$this->assertSame( array( $hook_name1, $hook_name2, $hook_name1, $hook_name1 ), $a->get_tags() );
+		$this->assertSame( array( $hook_name1, $hook_name2, $hook_name1, $hook_name1 ), $a->get_hook_names() );
 
 		remove_filter( 'all', array( $a, 'filterall' ) );
 		$this->assertFalse( has_filter( 'all', array( $a, 'filterall' ) ) );
@@ -211,7 +213,7 @@ class Tests_Filters extends WP_UnitTestCase {
 
 		// Make sure our hook was called correctly.
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 
 		// Now remove the filter, do it again, and make sure it's not called this time.
 		remove_filter( 'all', array( $a, 'filterall' ) );
@@ -220,7 +222,7 @@ class Tests_Filters extends WP_UnitTestCase {
 		$this->assertSame( $val, apply_filters( $hook_name, $val ) );
 		// Call cound should remain at 1.
 		$this->assertSame( 1, $a->get_call_count() );
-		$this->assertSame( array( $hook_name ), $a->get_tags() );
+		$this->assertSame( array( $hook_name ), $a->get_hook_names() );
 	}
 
 	/**

tests/phpunit/tests/user/author.php

@@ -173,6 +173,6 @@ class Tests_User_Author_Template extends WP_UnitTestCase {
 		get_the_author_link();
 
 		$this->assertSame( 1, $filter->get_call_count() );
-		$this->assertSame( array( 'the_author_link' ), $filter->get_tags() );
+		$this->assertSame( array( 'the_author_link' ), $filter->get_hook_names() );
 	}
 }