Debug Tests: Improve connection test, and allow overrides

_inc/lib/debugger/class-jetpack-cxn-test-base.php

@@ -1,4 +1,10 @@
 <?php
+/**
+ * Base class for Jetpack's debugging tests.
+ *
+ * @package Jetpack.
+ */
+
 use Automattic\Jetpack\Status;
 
 /**
@@ -239,17 +245,25 @@ public function list_fails( $type = 'all', $group = 'all' ) {
 	/**
 	 * Helper function to return consistent responses for a passing test.
 	 *
-	 * @param string $name Test name.
+	 * @param string      $name Test name.
+	 * @param string|bool $message Plain text message to show when test passed.
+	 * @param string|bool $label Label to be used on Site Health card.
+	 * @param string|bool $description HTML description to be used in Site Health card.
 	 *
 	 * @return array Test results.
 	 */
-	public static function passing_test( $name = 'Unnamed' ) {
+	public static function passing_test( $name = 'Unnamed', $message = false, $label = false, $description = false ) {
+		if ( ! $message ) {
+			$message = __( 'Test Passed!', 'jetpack' );
+		}
 		return array(
-			'name'       => $name,
-			'pass'       => true,
-			'message'    => __( 'Test Passed!', 'jetpack' ),
-			'resolution' => false,
-			'severity'   => false,
+			'name'        => $name,
+			'pass'        => true,
+			'message'     => $message,
+			'description' => $description,
+			'resolution'  => false,
+			'severity'    => false,
+			'label'       => $label,
 		);
 	}
 
@@ -277,15 +291,22 @@ public static function skipped_test( $name = 'Unnamed', $message = false ) {
 	 * @since 7.1.0
 	 * @since 7.3.0 Added $action for resolution action link, $severity for issue severity.
 	 *
-	 * @param string $name Test name.
-	 * @param string $message Message detailing the failure.
-	 * @param string $resolution Optional. Steps to resolve.
-	 * @param string $action Optional. URL to direct users to self-resolve.
-	 * @param string $severity Optional. "critical" or "recommended" for failure stats. "good" for passing.
+	 * @param string      $name Test name.
+	 * @param string      $message Message detailing the failure.
+	 * @param string      $resolution Optional. Steps to resolve.
+	 * @param string      $action Optional. URL to direct users to self-resolve.
+	 * @param string      $severity Optional. "critical" or "recommended" for failure stats. "good" for passing.
+	 * @param string      $label Optional. The label to use instead of the test name.
+	 * @param string|bool $action_label Optional. The label for the action url instead of default 'Resolve'.
+	 * @param string|bool $description Optional. An HTML description to override resolution.
 	 *
 	 * @return array Test results.
 	 */
-	public static function failing_test( $name, $message, $resolution = false, $action = false, $severity = 'critical' ) {
+	public static function failing_test( $name, $message, $resolution = false, $action = false, $severity = 'critical', $label = false, $action_label = false, $description = false ) {
+		if ( ! $action_label ) {
+			/* translators: Resolve is used as a verb, a command that when invoked will lead to a problem's solution. */
+			$action_label = __( 'Resolve', 'jetpack' );
+		}
 		// Provide standard resolutions steps, but allow pass-through of non-standard ones.
 		switch ( $resolution ) {
 			case 'cycle_connection':
@@ -301,12 +322,15 @@ public static function failing_test( $name, $message, $resolution = false, $acti
 		}
 
 		return array(
-			'name'       => $name,
-			'pass'       => false,
-			'message'    => $message,
-			'resolution' => $resolution,
-			'action'     => $action,
-			'severity'   => $severity,
+			'name'         => $name,
+			'pass'         => false,
+			'message'      => $message,
+			'resolution'   => $resolution,
+			'action'       => $action,
+			'severity'     => $severity,
+			'label'        => $label,
+			'action_label' => $action_label,
+			'description'  => $description,
 		);
 	}
 

_inc/lib/debugger/class-jetpack-cxn-tests.php

@@ -91,11 +91,40 @@ public static function increase_timeout() {
 	protected function test__check_if_connected() {
 		$name = __FUNCTION__;
 		if ( $this->helper_is_jetpack_connected() ) {
-			$result = self::passing_test( $name );
+			$result = self::passing_test(
+				$name,
+				__( 'Test passed!', 'jetpack' ),
+				__( 'Your site is connected to Jetpack', 'jetpack' ),
+				sprintf(
+					'<p>%1$s</p>' .
+					'<p><span class="dashicons pass"><span class="screen-reader-text">%2$s</span></span> %3$s</p>',
+					__( 'A healthy connection ensures Jetpack essential services are provided to your WordPress site, such as Stats and Site Security.', 'jetpack' ),
+					/* translators: Screen reader text indicating a test has passed */
+					__( 'Passed', 'jetpack' ),
+					__( 'Your site is connected to Jetpack.', 'jetpack' )
+				)
+			);
 		} elseif ( ( new Status() )->is_development_mode() ) {
 			$result = self::skipped_test( $name, __( 'Jetpack is in Development Mode:', 'jetpack' ) . ' ' . Jetpack::development_mode_trigger_text(), __( 'Disable development mode.', 'jetpack' ) );
 		} else {
-			$result = self::failing_test( $name, __( 'Jetpack is not connected.', 'jetpack' ), 'cycle_connection' );
+			$result = self::failing_test(
+				$name,
+				__( 'Jetpack is not connected.', 'jetpack' ),
+				'connect_jetpack',
+				admin_url( 'admin.php?page=jetpack#/dashboard' ),
+				'critical',
+				__( 'Your site is not connected to Jetpack', 'jetpack' ),
+				__( 'Reconnect your site now', 'jetpack' ),
+				sprintf(
+					'<p>%1$s</p>' .
+					'<p><span class="dashicons fail"><span class="screen-reader-text">%2$s</span></span> %3$s<strong> %4$s</strong></p>',
+					__( 'A healthy connection ensures Jetpack essential services are provided to your WordPress site, such as Stats and Site Security.', 'jetpack' ),
+					/* translators: screen reader text indicating a test failed */
+					__( 'Error', 'jetpack' ),
+					__( 'Your site is not connected to Jetpack.', 'jetpack' ),
+					__( 'We recommend reconnecting Jetpack.', 'jetpack' )
+				)
+			);
 		}
 
 		return $result;
@@ -229,7 +258,7 @@ protected function test__identity_crisis() {
 	}
 
 	/**
-	 * Tests connection status against wp.com's test-connection endpoint
+	 * Tests connection status against wp.com's test-connection endpoint.
 	 *
 	 * @todo: Compare with the wpcom_self_test. We only need one of these.
 	 *

_inc/lib/debugger/debug-functions.php

@@ -62,20 +62,41 @@ function jetpack_debugger_site_status_tests( $core_tests ) {
 				}
 				if ( false === $results['pass'] ) {
 					$return['label'] = $results['message'];
-					$return['status']      = $results['severity'];
+					if ( $results['label'] ) {
+						// Allow tests to override the strange message => label logic with an actual label.
+						$return['label'] = $results['label'];
+					}
+
+					// Most tests pass a `resolution` property to use as a description.
 					$return['description'] = sprintf(
 						'<p>%s</p>',
 						$results['resolution']
 					);
+
+					if ( $results['description'] ) {
+						// Allow tests to override 'resolution' with their own HTML description.
+						$return['description'] = $results['description'];
+					}
+
+					$return['status'] = $results['severity'];
 					if ( ! empty( $results['action'] ) ) {
 						$return['actions'] = sprintf(
-							'<a class="button button-primary" href="%1$s" target="_blank" rel="noopener noreferrer">%2$s <span class="screen-reader-text">%3$s</span><span aria-hidden="true" class="dashicons dashicons-external"></span></a>',
+							'<a href="%1$s" target="_blank" rel="noopener noreferrer">%2$s <span class="screen-reader-text">%3$s</span><span aria-hidden="true" class="dashicons dashicons-external"></span></a>',
 							esc_url( $results['action'] ),
-							__( 'Resolve', 'jetpack' ),
+							$results['action_label'],
 							/* translators: accessibility text */
 							__( '(opens in a new tab)', 'jetpack' )
 						);
 					}
+				} elseif ( true === $results['pass'] ) {
+					// Passing tests can chose to override defaults.
+					if ( $results['label'] ) {
+						$return['label'] = $results['label'];
+					}
+
+					if ( $results['description'] ) {
+						$return['description'] = $results['description'];
+					}
 				}
 
 				return $return;