Update comment on HTML Processor and test for seeking.

src/wp-includes/html-api/class-wp-html-processor.php

@@ -416,7 +416,12 @@ public function next_tag( $query = null ) {
 	/**
 	 * Steps through the HTML document and stop at the next token, if any.
 	 *
-	 * Currently only supports stepping through tags.
+	 * Currently only supports stepping through tags; do not use until this
+	 * supports visiting text nodes. This is necessary for now to ensure that
+	 * the Tag Processor doesn't bypass the HTML semantic rules in this class
+	 * when seeking to a bookmark.
+	 *
+	 * @access private
 	 *
 	 * @return bool
 	 */

tests/phpunit/tests/html-api/wpHtmlProcessorBreadcrumbs.php

@@ -515,7 +515,11 @@ public function test_can_query_an_element_by_tag_name() {
 	 * @covers WP_HTML_Processor::seek
 	 */
 	public function test_can_seek_back_and_forth() {
-		$p = WP_HTML_Processor::create_fragment( '<div><p one><div><p><div two><p><div><p><div><p three>' );
+		$p = WP_HTML_Processor::create_fragment(
+			<<<'HTML'
+<div>text<p one>more stuff<div><![CDATA[this is not real CDATA]]><p><!-- hi --><div two><p><div><p>three comes soon<div><p three>' );
+HTML
+		);
 
 		// Find first tag of interest.
 		while ( $p->next_tag() && null === $p->get_attribute( 'one' ) ) {