Explain tests that were previously asserting invalid behaviors.

dmsnell · dmsnell · commit 0440d836c0f7 · 2025-07-15T17:18:59.000-05:00
diff --git a/tests/phpunit/tests/formatting/wpAutop.php b/tests/phpunit/tests/formatting/wpAutop.php
@@ -536,6 +536,15 @@ public function data_element_sanity() {
 				"Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 ]]> -->",
 				"<p>Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 ]]> --></p>\n",
 			),
+			/*
+			 * CDATA sections do not exist within HTML, so even though it looks
+			 * like this should be escaping the entire “inner comment” span, there’s
+			 * actually an invalid comment starting at `<![CDATA[` and ending at
+			 * the very first `>` character, placing the end of the comment at
+			 * what looks like the end of the “normal comment” — the ` -->`. Everything
+			 * afterward is normal HTML data so the `<br>` is a real `BR` element and
+			 * the `]]>` is normal plaintext, not the CDATA terminator.
+			 */
 			array(
 				"Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 --> a\n9 ]]>",
 				"<p>Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 --> a<br />\n9 ]]></p>\n",
diff --git a/tests/phpunit/tests/formatting/wpHtmlSplit.php b/tests/phpunit/tests/formatting/wpHtmlSplit.php
@@ -30,6 +30,13 @@ public function data_basic_features() {
 				'abcd <!-- <html> --> efgh',
 				array( 'abcd ', '<!-- <html> -->', ' efgh' ),
 			),
+			/*
+			 * CDATA sections do not exist within HTML, so even though it looks
+			 * like this should be escaping the entire ` <html> ` span, there’s
+			 * actually an invalid comment starting at `<![CDATA[` and ending at
+			 * the very first `>` character, placing the end of the comment at
+			 * the end of `html>`. The rest is normal plaintext content.
+			 */
 			array(
 				'abcd <![CDATA[ <html> ]]> efgh',
 				array( 'abcd ', '<![CDATA[ <html>', ' ]]> efgh' ),
diff --git a/tests/phpunit/tests/rest-api/rest-comments-controller.php b/tests/phpunit/tests/rest-api/rest-comments-controller.php
@@ -3107,6 +3107,19 @@ public function test_comment_roundtrip_as_editor_unfiltered_html() {
 		}
 	}
 
+	/**
+	 * Ensures that saving a comment as a super-admin does not corrupt the
+	 * comment content when presented with common edge cases.
+	 *
+	 * Note that this test used to assert the wrong behavior due to a bug
+	 * in {@see wp_html_split()}. Whereby the unescaped `<` used to be
+	 * mistakenly identified as the start of an HTML tag or comment, this
+	 * led to accidental replacement “inside” the mistaken tag. The test
+	 * has been updated with `wp_html_split()` in accordance with the
+	 * HTML5 living specification.
+	 *
+	 * @ticket {TICKET_NUMBER}
+	 */
 	public function test_comment_roundtrip_as_superadmin() {
 		wp_set_current_user( self::$superadmin_id );
 
