Tests: Add unit tests for show_message()

[pbearne]

This ticket adds unit tests for the show_message() function in wp-admin/includes/misc.php. This function is responsible for displaying administration messages and handling WP_Error objects.

[pbearne]

The show_message() function is currently difficult to test because it has two major side effects:

1. Direct Output: It uses echo to print the message, requiring output buffering to capture it.
2. Buffer Flushing: It calls wp_ob_end_flush_all() and flush(), which force-closes all active output buffers. This interferes with PHPUnit's own output handling and makes it impossible to reliably use ob_start() within a test to capture the output.

Proposed Refactoring
To make show_message() testable while maintaining backward compatibility, we can split the formatting logic from the output logic.
Option 1: Add a return parameter (Recommended) We can add an optional second parameter $echo that defaults to true. When set to false, the function returns the HTML string instead of printing and flushing.

<?php
function show_message( $message, $echo = true ) {
    if ( is_wp_error( $message ) ) {
        if ( $message->get_error_data() && is_string( $message->get_error_data() ) ) {
            $message = $message->get_error_message() . ': ' . $message->get_error_data();
        } else {
            $message = $message->get_error_message();
        }
    }

    $output = "<p>$message</p>\n";

    if ( ! $echo ) {
        return $output;
    }

    echo $output;
    wp_ob_end_flush_all();
    flush();
}

Option 2: Extract a "get" version Create a new function get_show_message() that handles the string conversion and wrapping, and have show_message() call it.

<?php
function get_show_message( $message ) {
    if ( is_wp_error( $message ) ) {
        if ( $message->get_error_data() && is_string( $message->get_error_data() ) ) {
            return $message->get_error_message() . ': ' . $message->get_error_data();
        }
        return $message->get_error_message();
    }
    return $message;
}

function show_message( $message ) {
    echo "<p>" . get_show_message( $message ) . "</p>\n";
    wp_ob_end_flush_all();
    flush();
}

Why Option 1 is better for WordPress Core:

• It's a common pattern in WordPress (e.g., wp_dropdown_categories(), get_the_tag_list()).
• It allows tests to call show_message( $msg, false ) and assert the returned string without causing "risky" test warnings in PHPUnit.
• It doesn't introduce a new global function that might have naming conflicts or limited utility.

Would you like me to implement one of these changes and update the tests accordingly?

[desrosj]

Adding the tests focus, which is used to indicate a ticket is solely focused on adding tests.

This pull request updates the show_message function in src/wp-admin/includes/misc.php to add support for returning the formatted message as a string instead of always printing it.
Without this change, it is almost impossible to add tests for this show_message function because of buffer flushing functions called at the end of it's definition.

Enhancements to message display:

• Updated the show_message function to accept a new $echo parameter (defaulting to true). When $echo is false, the function returns the formatted HTML string instead of printing it and flushing output buffers. The function signature and docblock were updated accordingly.

Testing improvements:

• Added a new test class Tests_Admin_Includes_Misc_ShowMessage_Test in tests/phpunit/tests/admin/includes/misc/ShowMessage_Test.php to verify that show_message correctly returns the formatted HTML string for plain messages and WP_Error objects when $echo is false.