New PHPUnit assertion in WP 6.9 (`assertEqualHTML`) to compare HTML

[bph]

Discussed in #432

^{Originally posted by juanmaguitar December 3, 2025}
WordPress 6.9 introduces a new PHPUnit assertion on WP_UnitTestCase: assertEqualHTML(). Instead of comparing raw HTML strings with assertSame(), this assertion compares semantic HTML output, avoiding brittle failures caused by attribute order, quote style, whitespace, or self-closing tags.

This article would show developers how to use assertEqualHTML() in real-world tests for filters, block rendering, HTML API transformations, and block HTML filtered to add Interactivity API directives. It would highlight how this assertion improves both failure output and test stability when working with complex, block-based markup.

Key points for the article:

• Problem: Existing HTML tests using assertSame() are fragile and often fail on insignificant markup changes.
• What assertEqualHTML() does: Compares two HTML strings as normalized HTML/DOM (and is block-aware), not as literal text.
• Real-world examples:
  • Testing a content filter that modifies <img> tags using the HTML API.
  • Testing dynamic block render callbacks that output complex block markup.
  • Testing filters that augment block HTML with Interactivity API directives (e.g., adding data-wp-interactive attributes or data-wp-on--click handlers) while keeping the tests resilient to markup normalization.
• Better diffs: Demonstrate how failures highlight meaningful differences (block type, attributes, values) instead of noisy string diffs.
• Migration tips: When to replace assertSame() with assertEqualHTML() in existing tests, and when exact string comparisons are still appropriate.

References:

• Dev note: Updates to the HTML API in 6.9
• HTML API: https://developer.wordpress.org/reference/classes/wp_html_tag_processor/
• Interactivity API: https://developer.wordpress.org/block-editor/reference-guides/interactivity-api/
• Uses in WP Core

Audience: WordPress core contributors, plugin/theme developers with PHPUnit test suites, and anyone testing HTML or block output in WordPress.

[!Note]
The article should focus on practical, copy‑pasteable test examples—including one where a filter injects Interactivity API directives into block HTML—showing how assertEqualHTML() behaves in real projects.

cc: @sirreal

[juanmaguitar]

I have created a draft for the article. It's available at:
https://docs.google.com/document/d/1ZNHP-_CGfJserY3emR264Dg2Ts5it8_A7r32G5Gjs9w/edit?usp=sharing

[juanmaguitar]

Thanks @sirreal for the first (and technical) review. I have addressed all your feedback.

The draft is ready for another review.

[bph]

@juanmaguitar Nice flow of the article! And great examples! Of course, I left some comments, just minor things, though.