Tests: Add new `assertEqualHTML` assertion #8882

ockham · 2025-06-02T13:54:06Z

Proposed changes

Add assertEqualHTML method to WP_UnitTestClass for tests comparing HTML (potentially including block markup).

Comparing HTML markup can be error prone and fragile. Typically we're interested in semantically equivalent HTML, which is what this assertion allows for; i.e. it has built-in tolerance for different attribute and class name order.

Internally, it builds a deterministic tree string representation of the HTML (using the HTML API) and compares the results.

The format of the tree is inspired by the HTML5lib-tests tree format.. It is extended with a special representation of block delimiters and their attributes.

This format also makes it easier to visually spot the differences between the two strings of HTML markup, as reported by the assertion. Quoting the inline documentation (PHPDoc) that's part of this PR:

For example, consider the following block markup:

    <!-- wp:separator {"className":"is-style-default has-custom-classname","style":{"spacing":{"margin":{"top":"50px","bottom":"50px"}}},"backgroundColor":"accent-1"} -->
        <hr class="wp-block-separator is-style-default has-custom-classname" style="margin-top: 50px; margin-bottom: 50px" />
    <!-- /wp:separator -->

This will be represented as:

    BLOCK["core/separator"]
      {
        "backgroundColor": "accent-1",
        "className": "has-custom-classname is-style-default",
        "style": {
          "spacing": {
            "margin": {
              "top": "50px",
              "bottom": "50px"
            }
          }
        }
      }
      <hr>
        class="has-custom-classname is-style-default wp-block-separator"
        style="margin-top:50px;margin-bottom:50px;"

Note

Edit: Fixed by @sirreal, see #8882 (comment).

This PR adds the new assertEqualBlockMarkup method to the WP_UnitTestCase class. Note that class Tests_Dependencies_Scripts, which is a subclass of WP_UnitTestCase, already contains a protected method named assertEqualMarkup. The latter is exclusively used for dependencies/scripts tests. The new assertEqualBlockMarkup cannot be used as a drop-in replacement, due to some differences in what it considers semantically equivalent HTML.

The existence of that protected assertEqualMarkup method was a consideration in naming the new method assertEqualBlockMarkup, so that it wouldn't collide. It seems like a reasonable choice, given that assertEqualBlockMarkup is indeed capable not only of parsing HTML, but also block markup.

In a future iteration, we might choose to retire the existing assertEqualMarkup method (and use assertEqualBlockMarkup for dependencies/scripts tests). This would then also pave the way for a general-purpose assertEqualMarkup method (which is able to parse HTML but agnostic of block markup), should the need arise.

Props @sirreal @dmsnell
Trac ticket: https://core.trac.wordpress.org/ticket/63527

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.

…cripts

tests/phpunit/tests/build-tree-representation.php

tests/phpunit/includes/build-tree-representation.php

…encies_Scripts" This reverts commit c01a3c1.

github-actions · 2025-06-02T14:29:00Z

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.

tests/phpunit/includes/build-tree-representation.php

tests/phpunit/tests/dependencies/scripts.php

tests/phpunit/includes/build-tree-representation.php

The generated HTML produces async="async" or defer="defer". Match this in the expected HTML.

…ferent_ HTML

sirreal · 2025-06-05T16:43:07Z

I've pushed some changes to completely remove the previous assertEqualMarkup with this implementation.

The work discovered at least one bug in the tests where the previous implementation "normalized" the output and forced the markup to appear equivalent when, in face, it was not. In this case, it purported to test html5 script behavior, but did not set html5 theme support.

wordpress-develop/tests/phpunit/tests/dependencies/scripts.php

Lines 1531 to 1534 in b0df96a

    
           public function test_wp_enqueue_script_with_html5_support_does_not_contain_type_attribute() { 
        
           	global $wp_version; 
        
           	$this->add_html5_script_theme_support();

There are a number of changes where /* <![CDATA[ */ /* ]]> */ wrappers are introduced around script tag contents or attributes were produced like defer="defer" instead of booleans.

It's clear that this implementation of assertEqualMarkup provides a much more accurate representation of the markup.

There's a conversation to be had around HTML5 support and whether the non HTML5 behaviors even make sense today, but that's beyond the scope of this PR.

sirreal · 2025-06-05T17:05:17Z

tests/phpunit/tests/dependencies/scripts.php

+		$expected .= "<script type=\"text/javascript\" src=\"http://example.com\" id=\"test-example-js\"></script>\n";
+		$expected .= "<script type=\"text/javascript\" id=\"test-example-js-after\">\n/* <![CDATA[ */\nconsole.log(\"after\");\n/* ]]> */\n</script>\n";


There are a few cases like this where the contents of an (IE conditional) HTML comment were changed.

These script tags, on their own, would be recognized as equivalent with double " or single ' quotes. But they're not script tags, they are the text contents of an HTML comment where ' is not the same as ".

sirreal · 2025-06-05T17:11:07Z

All of the tests here for IE conditional comments also seem quite out of place in today's internet.

sirreal

I've left some feedback but I think this is great and ready to go for the most part. It becomes much easier and less error prone to compare HTML.

It's worth mentioning that the tree builder functionality is largely duplicated from existing html5lib tests used for the HTML API. It's already seen significant usage, although the block parsing is new.

wordpress-develop/tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php

Line 159 in 75f4a09

    
           private static function build_tree_representation( ?string $fragment_context, string $html ) {

tests/phpunit/includes/build-equivalent-html-semantic-tree.php

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

ockham · 2025-06-10T08:49:57Z

It's worth mentioning that the tree builder functionality is largely duplicated from existing html5lib tests used for the HTML API. It's already seen significant usage, although the block parsing is new.

@sirreal Think it's worth doing a follow-up to share code between the two?

sirreal · 2025-06-10T09:14:05Z

I only mentioned it because it seemed relevant for other reviewers. We could try out the sharing but I don't think it's necessary.

github-actions · 2025-06-10T10:24:15Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 60295
GitHub commit: fe6c27b

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

ockham added 5 commits June 2, 2025 14:43

Tests: Add assertEqualMarkup trait

00617e7

Add test coverage for assertion helper method

cbba80a

Fix include path

0602711

Remove now-obsolete method of the same name from Tests_Dependencies_S…

c01a3c1

…cripts

Remove obsolete require_lib

5a5b2b1

ockham self-assigned this Jun 2, 2025

ockham added 4 commits June 2, 2025 15:55

Add since PHPDoc

1cb1f23

Move assertion to class WP_UnitTestCase_Base

38b575a

Get rid of trait

8204474

WPCS

03f7b09

ockham changed the title ~~Add/assert equal markup~~ Tests: Add new assertEqualMarkup assertion Jun 2, 2025

Remove potentially obsolete PHPCS ignore

09cf449

ockham commented Jun 2, 2025

View reviewed changes

tests/phpunit/tests/build-tree-representation.php Outdated Show resolved Hide resolved

ockham commented Jun 2, 2025

View reviewed changes

tests/phpunit/includes/build-tree-representation.php Outdated Show resolved Hide resolved

Revert "Remove now-obsolete method of the same name from Tests_Depend…

b2fc3ff

…encies_Scripts" This reverts commit c01a3c1.

ockham mentioned this pull request Jun 2, 2025

Ensure block editor preloading middleware JSON is correctly escaped #8145

Closed

ockham added 6 commits June 2, 2025 16:31

Bring back assertEqualMarkup override, harmonize signature

ef27f4f

Remove trailing newline

51e4613

Fix class name

2258487

Tweak tests

5bfdf9b

Remove strict_types declaration

2b33187

Fix heredoc indentation for PHP 7.2 compat :rolleyes:

82d57b6

sirreal reviewed Jun 2, 2025

View reviewed changes

tests/phpunit/includes/build-tree-representation.php Outdated Show resolved Hide resolved

tests/phpunit/tests/dependencies/scripts.php Outdated Show resolved Hide resolved

dmsnell reviewed Jun 3, 2025

View reviewed changes

tests/phpunit/includes/build-tree-representation.php Show resolved Hide resolved

dmsnell reviewed Jun 3, 2025

View reviewed changes

tests/phpunit/includes/build-tree-representation.php Show resolved Hide resolved

dmsnell reviewed Jun 3, 2025

View reviewed changes

tests/phpunit/includes/build-tree-representation.php Outdated Show resolved Hide resolved

ockham added 3 commits June 3, 2025 14:30

Use WP_Block_Parser for block parsing

3fbf857

Handle void blocks correctly

3090d65

Rearrange logic

47dccc1

sirreal added 11 commits June 5, 2025 18:36

Rename test helper to assertEqualMarkup

98ad4c9

Fix script async/defer strategy expectation to match printed scripts

492316d

Add CDATA inline script wrappers where they appear in markup

c7317e7

FIXME: Skip an inaccurate test

7472609

Adjust expected output to use attributes as generated

844a076

The generated HTML produces async="async" or defer="defer". Match this in the expected HTML.

Add html5 support to a test that expects html5 support

514967f

Script quotes in IE7 conditional _comments_ produce semantically _dif…

fed7647

…ferent_ HTML

Revert irrelevant change

28e1fd7

Fix more missing CDATA comments

c2f1bfa

Remove scripts specific assertEqualMarkup implementation

5a60a70

Use more consistent code backticks in docblock

b0df96a

Fix phpcs issues

1cb1daf

sirreal reviewed Jun 5, 2025

View reviewed changes

Remove now-obsolete parse_markup_fragment() method

defbe92

sirreal approved these changes Jun 6, 2025

View reviewed changes

ockham and others added 3 commits June 10, 2025 10:26

Fix PHPDoc param order

2b66454

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

Tweak PHPDoc description of build_equivalent_semantic_tree

95ddd9a

Co-authored-by: Jon Surrell <sirreal@users.noreply.github.com>

Add return type, tweak PHPDoc

6a79216

ockham added 2 commits June 10, 2025 11:08

Rename to build_visual_html_tree

9469f43

Rename to assertEqualHTML

b07677e

ockham changed the title ~~Tests: Add new assertEqualBlockMarkup assertion~~ Tests: Add new assertEqualHTML assertion Jun 10, 2025

ockham added 2 commits June 10, 2025 11:57

Fix indentation

f7736c4

Add ticket annotations

a83ff2b

github-actions bot closed this Jun 10, 2025

ockham deleted the add/assert-equal-markup branch June 10, 2025 10:25

		$expected .= "<script type=\"text/javascript\" src=\"http://example.com\" id=\"test-example-js\"></script>\n";
		$expected .= "<script type=\"text/javascript\" id=\"test-example-js-after\">\n/* <![CDATA[ /\nconsole.log(\"after\");\n/ ]]> */\n</script>\n";

Tests: Add new assertEqualHTML assertion #8882

Tests: Add new assertEqualHTML assertion #8882

Uh oh!

Conversation

ockham commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Note

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jun 2, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sirreal commented Jun 5, 2025

Uh oh!

sirreal Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirreal commented Jun 5, 2025

Uh oh!

sirreal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ockham commented Jun 10, 2025

Uh oh!

sirreal commented Jun 10, 2025

Uh oh!

github-actions bot commented Jun 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Tests: Add new `assertEqualHTML` assertion #8882

Tests: Add new `assertEqualHTML` assertion #8882

ockham commented Jun 2, 2025 •

edited

Loading

sirreal Jun 5, 2025 •

edited

Loading