WordPress Site Health Custom Test Example: Surface Production Checks

Last reviewed: April 21, 2026

WordPress Site Health is useful because it puts operational problems where administrators already look: inside wp-admin. A plugin can use that surface to expose production checks such as missing object cache, disabled cron, old PHP extensions, failed API connectivity, or unsafe configuration.

This article shows how to add a custom Site Health test from a plugin. The point is not to create noise. The point is to surface checks that genuinely affect reliability, security, or performance.

Problem it solves

Many production issues are discovered too late because they live in logs, server config, or external dashboards that editors never see. A focused Site Health check can turn hidden technical state into an actionable admin notice without adding another settings screen.

Register a direct Site Health test

<?php
/**
 * Plugin Name: VulnWP Site Health Checks
 * Description: Adds a custom Site Health test for production readiness.
 * Version: 1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

add_filter( 'site_status_tests', 'vulnwp_register_site_health_tests' );

function vulnwp_register_site_health_tests( $tests ) {
	$tests['direct']['vulnwp_object_cache_check'] = array(
		'label' => __( 'Persistent object cache availability', 'vulnwp-health' ),
		'test'  => 'vulnwp_site_health_object_cache_check',
	);

	return $tests;
}

function vulnwp_site_health_object_cache_check() {
	$using_cache = wp_using_ext_object_cache();

	if ( $using_cache ) {
		return array(
			'label'       => __( 'Persistent object cache is active', 'vulnwp-health' ),
			'status'      => 'good',
			'badge'       => array(
				'label' => __( 'Performance', 'vulnwp-health' ),
				'color' => 'blue',
			),
			'description' => '<p>' . esc_html__( 'This site is using an external object cache drop-in.', 'vulnwp-health' ) . '</p>',
			'actions'     => '',
			'test'        => 'vulnwp_object_cache_check',
		);
	}

	return array(
		'label'       => __( 'Persistent object cache is not active', 'vulnwp-health' ),
		'status'      => 'recommended',
		'badge'       => array(
			'label' => __( 'Performance', 'vulnwp-health' ),
			'color' => 'orange',
		),
		'description' => '<p>' . esc_html__( 'High-traffic sites should consider Redis, Memcached, or another persistent object cache.', 'vulnwp-health' ) . '</p>',
		'actions'     => '<p>' . esc_html__( 'Review hosting support and enable a persistent object cache if the workload requires it.', 'vulnwp-health' ) . '</p>',
		'test'        => 'vulnwp_object_cache_check',
	);
}

Status levels

Use good when the check passes, recommended when the issue is worth attention, and critical only when the site is meaningfully at risk. Do not mark every preference as critical. Administrators will ignore Site Health if plugins turn it into a warning wall.

Direct vs async tests

Direct tests run as part of the Site Health page load. Keep them fast. If a check calls an external API, scans many files, or performs a slow database operation, use an async test instead or cache the result. A Site Health check should not make wp-admin feel broken.

A practical pattern is to store the last expensive check result in an option or transient, refresh it on a schedule, and let Site Health report the latest known state. That avoids making every administrator wait for a remote service to respond.

Visibility and permissions

Site Health is an admin surface, but that does not mean every detail should be shown carelessly. Avoid printing full server paths, internal hostnames, API responses, credentials, or provider-specific secrets. A good check explains the impact and next action without exposing infrastructure unnecessarily.

What to test

• External API connectivity for a plugin that depends on an upstream service.
• Whether required PHP extensions are available.
• Whether scheduled plugin jobs are registered.
• Whether a required upload directory is writable.
• Whether production-only settings are accidentally enabled or disabled.

Common mistakes

• Testing preferences instead of risks. Site Health should show operationally important signals.
• Doing slow work in direct tests. Use async tests or cache expensive checks.
• Returning vague actions. The administrator should know what to fix next.
• Exposing secrets. Never print API keys, paths with private data, or raw upstream responses.
• Marking everything critical. Severity inflation makes real incidents easier to miss.

Production checklist

• Keep checks fast and deterministic.
• Use translated labels and escaped descriptions.
• Give every failing check a concrete action.
• Avoid leaking internal infrastructure details to low-privilege users.
• Test with the same plugins and hosting stack used in production.

Related reading

For cache-specific implementation details, read our Object Cache example. For scheduled checks, pair this with the WP-Cron reliability checklist.

References and further reading

• WordPress Code Reference: site_status_tests
• WordPress Code Reference: wp_using_ext_object_cache()