Improve robustness of page cache test for Site Health by westonruter · Pull Request #10855 · WordPress/wordpress-develop

westonruter · 2026-02-03T18:48:16Z

This improves the robustness of page cache detection in Site Health by refining the response header validation and expanding support for common caching layers.

Logic & Header Improvements

Stricter Cache Hit Matching: The $cache_hit_callback now uses a word-boundary regular expression (/\bhit\b/i) instead of a simple substring check. This prevents false positives from header values like shit. 💩
X-SRCache-Store-Status Correction: Fixed the validation for this header to check for the correct value STORE (the module's indicator for a successful cache storage) instead of HIT.
Varnish Support: Added detection for the X-Varnish header, specifically identifying a hit when the header contains two request IDs (e.g., 123 456), as documented in the Varnish FAQ.
Documentation: Added detailed docblocks and source links for caching headers (e.g., srcache, Varnish) and explicitly listed supported generic proxies (Squid, Go, Fastly, LiteSpeed) in comments.

PHPUnit Test Enhancements

Comprehensive Test Cases: Added new test scenarios to Tests_Admin_wpSiteHealth to verify:
- X-Varnish hits vs. misses.
- X-SRCache-Store-Status (STORE) and X-SRCache-Fetch-Status (HIT).
- Prevention of false positives from substrings (e.g., x-cache: shit).
- Robustness of standard headers like ETag, Last-Modified, and Via.
Improved Typing: Updated the test suite with strict parameter and return types for data providers and test methods, aligning with modern PHP standards and resolving PHPStan reported issues.

Code Quality

Applied consistent formatting to class-wp-site-health.php and the test suite using composer format to ensure adherence to WordPress Coding Standards.

Trac ticket: https://core.trac.wordpress.org/ticket/64370

Use of AI Tooling

The above PR description was drafted by Gemini, and Gemini CLI was involved in authoring some commits (as attributed via co-authored-by).

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

This commit updates the page cache detection in Site Health by: - Using a stricter regex (\bhit\b) for detecting cache hits in response headers, preventing false positives (e.g., 'shit'). - Adding support for the X-Varnish header, identifying a cache hit when it contains two request IDs. - Adding documentation and source links for the supported headers. - Adding PHPUnit test cases to verify the new detection logic. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

The x-srcache-store-status header uses 'STORE' or 'BYPASS', not 'HIT' or 'MISS'. This update ensures that 'STORE' is correctly identified as a positive page cache indicator. Also includes: - Documentation for srcache headers. - Explicit list of generic caching proxies (Squid, Go, Fastly, LiteSpeed) in comments. - Test cases for x-srcache-store-status and x-srcache-fetch-status. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

github-actions · 2026-02-03T18:48:30Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter, dmsnell.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

westonruter · 2026-02-03T18:52:28Z

Gemini review:

I have completed the review of the changes committed to the trac-64370 branch.

Commit Context

The changes aim to improve the robustness of page cache detection in WordPress Site Health. Key improvements include:

Using stricter regex (\bhit\b) to prevent false positives from header values like "shit".
Adding support for the X-Varnish header by detecting the specific hit format (two request IDs).
Correcting x-srcache-store-status detection to look for STORE instead of HIT.
Improving documentation and PHPStan typing for the detection methods and tests.

Code Review

`src/wp-admin/includes/class-wp-site-health.php`

Logic Improvement: The move from str_contains to preg_match( '/\bhit\b/i', ... ) is an excellent fix for substring-related false positives.
Varnish Header: The x-varnish callback correctly implements the detection of a hit by checking for two space-separated digits, matching Varnish's debugging header behavior.
SRCache Correction: Updating x-srcache-store-status to check for STORE is correct as per the module's documentation.
Coding Standards:
- The use of array shape return types (array<string, ?callable>) in docblocks aligns with current project goals for PHPStan level 10 compatibility.
- The addition of the : array return type hint is compatible with PHP 7.4.
Nitpick: The via header is restored but set to null (existence check). While standard, many proxies use Via without caching. However, given the context of other headers, this is a reasonable heuristic for WordPress core.

`tests/phpunit/tests/admin/wpSiteHealth.php`

Type Safety: The addition of strict types to properties and method signatures (private WP_Site_Health $instance;, test_get_page_cache( array $responses, ... )) is a great improvement for the test suite's reliability.
PHPStan Resolution: The return type for data_get_page_cache has been meticulously defined to match the complex array structure returned, which should resolve the reported PHPStan errors.
Test Coverage:
- New cases for false-positive-hit-in-word, varnish-header, and srcache variants provide thorough coverage for the logic changes.
- The last-modified test case uses a realistic date string, which is better than the previous "hit" value.
Consistency: The change from null to false for good_basic_auth in the data provider, coupled with the signature change to bool, ensures type consistency.

Summary

The changes are high quality, follow WordPress coding standards, and significantly improve the reliability of Site Health's page cache detection. No regressions or standards violations were identified.

Recommendation: Ready for merge.

github-actions · 2026-02-03T18:55:11Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

westonruter · 2026-02-03T20:18:48Z

src/wp-admin/includes/class-wp-site-health.php

 			'x-cache-disabled'       => static function ( $header_value ) {
 				return ( 'on' !== strtolower( $header_value ) );
 			},
-			'x-srcache-store-status' => $cache_hit_callback,


This was incorrect. Now fixed.

…into trac-64370

westonruter · 2026-02-17T18:45:53Z

tests/phpunit/tests/admin/wpSiteHealth.php

 	 * @covers ::get_page_cache_headers()
 	 * @covers ::check_for_page_caching()
 	 */
-	public function test_get_page_cache( $responses, $expected_status, $expected_label, $good_basic_auth = null, $delay_the_response = false ) {


Note that $good_basic_auth was previously only either null or false, so this is now changed to be an actual boolean with true or false.

dmsnell

sorry I can’t give a more thorough review at the moment. it’s nice seeing iteration on the screen.

src/wp-admin/includes/class-wp-site-health.php

dmsnell · 2026-02-17T19:11:06Z

src/wp-admin/includes/class-wp-site-health.php

 	 * @since 6.1.0
 	 *
-	 * @return array List of client caching headers and their (optional) verification callbacks.
+	 * @return array<string, ?callable> Mapping of page caching headers and their (optional) verification callbacks.


the previous comment explained what an empty value means, but this change removes that knowledge. was that intentional?

I thought it was redundant, but it seems it isn't. How about this:

Suggested change

* @return array<string, ?callable> Mapping of page caching headers and their (optional) verification callbacks.

* @return array<string, ?callable> Mapping of page caching headers and their (optional) verification callbacks.

A null value means a simple existence check is used for the header.

src/wp-admin/includes/class-wp-site-health.php

tests/phpunit/tests/admin/wpSiteHealth.php

dmsnell · 2026-02-17T19:29:23Z

tests/phpunit/tests/admin/wpSiteHealth.php

+				),
+				'expected_status' => 'good',
+				'expected_label'  => $good_label,
+			),


because I’m not familiar with all of these systems, and don’t have any in front of me, I am not reviewing or verifying these tests.

I’m trusting that you confirmed that the responses correspond to what those projects actually produce and that the values here are factually representative.

the CommonCrawl archive would potentially be a valuable archive to mine for this kind of header behavior.

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

… value Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

westonruter · 2026-02-17T20:53:18Z

src/wp-admin/includes/class-wp-site-health.php

+			/**
+			 * Custom caching headers.
+			 *
+			 * These do not seem to be actually used by any caching layers. There were first introduced in a Site Health
+			 * test in the AMP plugin. They were copied into the Performance Lab plugin's Site Health test before they
+			 * were merged into core.
+			 *
+			 * @link https://github.com/ampproject/amp-wp/pull/6849
+			 * @link https://github.com/WordPress/performance/pull/263
+			 * @link https://core.trac.wordpress.org/changeset/54043
+			 */
 			'x-cache-enabled'        => static function ( $header_value ) {
-				return 'true' === strtolower( $header_value );
+				return ( 'true' === strtolower( $header_value ) );
 			},
 			'x-cache-disabled'       => static function ( $header_value ) {
 				return ( 'on' !== strtolower( $header_value ) );
 			},


I'm inclined to remove these entirely since it seems they were originally introduced erroneously in the AMP plugin. I can't find any caching layers that actually use them. There are a few hundred mentions of them on GitHub, nevertheless: https://github.com/search?q=%2Fx-cache-(enabled%7Cdisabled)%2F&type=code

westonruter and others added 4 commits February 3, 2026 09:27

Improve docs and typing for get_page_cache_headers method

9aa2b94

Tidy test_get_page_cache

ed21256

westonruter requested a review from dmsnell February 3, 2026 18:59

westonruter commented Feb 3, 2026

View reviewed changes

westonruter added 2 commits February 11, 2026 12:19

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

a6ffaaf

…into trac-64370

Merge branch 'trunk' into trac-64370

f9512d5

westonruter commented Feb 17, 2026

View reviewed changes

Rename good_basic_auth to has_basic_auth since not necessarily good

5a7b2f5

dmsnell reviewed Feb 17, 2026

View reviewed changes

westonruter and others added 9 commits February 17, 2026 11:31

Fix typo in comment

de5b813

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Replace bool type cast with explicit equality for preg_match() return…

c51daae

… value Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Remove vulgarity from test

913d8cb

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Move via header up to standard section

c63928a

Re-organized cache headers

6f1ff6a

Add nginx section and add links for Varnish

4af0c36

Move x-proxy-cache into Nginx section

1aded16

Replace word boundary for HIT with anchor, comma, or whitespace

c67ffac

Add documentation for x-cache-enabled and x-cache-disabled

40770d1

westonruter commented Feb 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve robustness of page cache test for Site Health#10855

Improve robustness of page cache test for Site Health#10855
westonruter wants to merge 16 commits intoWordPress:trunkfrom
westonruter:trac-64370

westonruter commented Feb 3, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

westonruter commented Feb 3, 2026

Uh oh!

github-actions bot commented Feb 3, 2026

Uh oh!

westonruter Feb 3, 2026

Uh oh!

westonruter Feb 17, 2026

Uh oh!

dmsnell left a comment

Uh oh!

Uh oh!

dmsnell Feb 17, 2026

Uh oh!

westonruter Feb 17, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dmsnell Feb 17, 2026

Uh oh!

westonruter Feb 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	* @return array<string, ?callable> Mapping of page caching headers and their (optional) verification callbacks.
	* @return array<string, ?callable> Mapping of page caching headers and their (optional) verification callbacks.
	A null value means a simple existence check is used for the header.

Conversation

westonruter commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Logic & Header Improvements

PHPUnit Test Enhancements

Code Quality

Use of AI Tooling

Uh oh!

github-actions bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

westonruter commented Feb 3, 2026

Commit Context

Code Review

src/wp-admin/includes/class-wp-site-health.php

tests/phpunit/tests/admin/wpSiteHealth.php

Summary

Uh oh!

github-actions bot commented Feb 3, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

westonruter Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

dmsnell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dmsnell Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dmsnell Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

westonruter commented Feb 3, 2026 •

edited

Loading

github-actions bot commented Feb 3, 2026 •

edited

Loading

`src/wp-admin/includes/class-wp-site-health.php`

`tests/phpunit/tests/admin/wpSiteHealth.php`