Users: Add new hooks to filter retrieve password emails.

This change introduces two new hooks to help developers to filter retrieve password emails:

- `send_retrieve_password_email` can be used to filter whether to send the retrieve password email;
- `retrieve_password_notification_email` can be used to filter the contents of the reset password notification email sent to the user.

This changesets also adds unit tests for these new filters.

Props connapptivity, costdev, audrasjb, johnbillion.
Fixes #54690.


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

tests/phpunit/tests/user/retrievePassword.php

@@ -0,0 +1,60 @@
+<?php
+/**
+ * Test cases for the `retrieve_password()` function.
+ *
+ * @package WordPress
+ * @since 6.0.0
+ */
+
+/**
+ * Test retrieve_password(), in wp-includes/user.php.
+ *
+ * @group user
+ *
+ * @covers ::retrieve_password
+ */
+class Tests_User_RetrievePassword extends WP_UnitTestCase {
+	/**
+	 * Test user.
+	 *
+	 * @since 6.0.0
+	 *
+	 * @var WP_User $user
+	 */
+	protected $user;
+
+	public function set_up() {
+		parent::set_up();
+
+		// Create the user.
+		$this->user = self::factory()->user->create_and_get(
+			array(
+				'user_login' => 'jane',
+				'user_email' => 'r.jane@example.com',
+			)
+		);
+	}
+
+	/**
+	 * @ticket 54690
+	 */
+	public function test_retrieve_password_reset_notification_email() {
+		$message = 'Sending password reset notification email failed.';
+		$this->assertNotWPError( retrieve_password( $this->user->user_login ), $message );
+	}
+
+	/**
+	 * @ticket 54690
+	 */
+	public function test_retrieve_password_should_return_wp_error_on_failed_email() {
+		add_filter(
+			'retrieve_password_notification_email',
+			static function() {
+				return array( 'message' => '' );
+			}
+		);
+
+		$message = 'Sending password reset notification email succeeded.';
+		$this->assertWPError( retrieve_password( $this->user->user_login ), $message );
+	}
+}