PHPUnit tests that check HTML output are notoriously fragile. A simple refactor that reorders attributes — or a dependency update that tweaks whitespace — can break a passing test even though the rendered result is identical.

The new WP_UnitTestCase::assertEqualHTML() method, available since WP 6.9, compares HTML semantically rather than as raw strings. Under the hood it uses WP_HTML_Processor to parse both strings into normalized trees, so these two assertions are equivalent:

// These are semantically identical 
— assertEqualHTML() passes, assertSame() fails
'<img loading="lazy" src="photo.jpg">'
'<img src="photo.jpg" loading="lazy">'

// These are semantically identical 
— assertEqualHTML() passes, assertSame() fails
'<img loading="lazy" src="photo.jpg">'
'<img src="photo.jpg" loading="lazy">'

It normalizes attribute order, class name sequence, style formatting, whitespace, and HTML character references. It still catches real differences: wrong attribute values, missing elements, changed content.

If you write tests for blocks, HTML API transformations, or Interactivity API directives, this will save you from a whole class of false failures.

I wrote about it in the following article for the WordPress Developer Blog.