Make find() search descendants only, as jQuery does

find() treated the nodes already in the match set as candidates for their own
selector, so qp($xml, '#a1')->find('a') returned #a1 itself alongside any nested
<a>. jQuery's .find() searches descendants; filter() is what asks whether the
nodes in hand match.

The document element keeps its self-match. qp() seeds the match set with the
document element rather than with the document node, so it stands in for
$(document), and without the exception qp($xml)->find('root') could never match.

This depends on #72. Before it, the selector-filtered traversal methods reach
is(), which reached find(), so they relied on the self-match to test a node
against a selector; changing find() on its own breaks nine of them. Once those
go through NodeMatcher they no longer care.

testBefore searched for the node it was standing on. Rewritten to search from
top(), which is the shape the next two assertions in that test already use.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

CHANGELOG.md

@@ -15,6 +15,7 @@ QueryPath Changelog
 - Apply the same fix to the other selector-filtered traversal methods in `QueryPath\Helpers\QueryFilters`: `parent()`, `parents()`, `parentsUntil()`, `closest()`, `next()`, `nextAll()`, `nextUntil()`, `prev()`, `prevAll()`, `prevUntil()`, `siblings()`, and `not()` (#62)
 - **Behaviour change:** `parents()` and `parentsUntil()` now return their results in reverse document order with duplicates removed, as jQuery does. Previously a set built from more than one starting element was grouped by starting element (#62)
 - **Breaking behaviour change:** `DOMQuery::filter()` now narrows the match set to the members that match the selector, as jQuery does, instead of keeping any element that merely *contains* a match. `qp($file, 'inner')->filter('li')` returned both `<inner>` elements and now returns none. Use `has()` for the old behaviour
+- **Breaking behaviour change:** `find()` now searches descendants only, as jQuery's `.find()` does. A node already in the match set is no longer a candidate for its own selector, so `qp($xml, '#a1')->find('a')` no longer returns `#a1` itself. The document element remains matchable, because `qp()` seeds the match set with it rather than with the document. Use `filter()` to match the nodes in hand
 - Fix `children($selector)`, which resolved `:scope` against each child rather than the document element, so `children(':scope')` matched every child
 - `filter()` and `children($selector)` now evaluate the selector against the whole candidate set in a single pass, rather than one node at a time. A per-node pass cannot evaluate a selector describing a position within the set, since each node is the only member of its own one-element set
 - `nextAll()` and `prevAll()` stop walking at the first sibling already collected from an earlier starting element, rather than re-walking to the end of the list. On a 4,000-item list `nextAll()` fell from about 430 ms to under 10 ms

src/CSS/DOMTraverser.php

@@ -814,8 +814,11 @@ protected function initialMatchOnElement(SimpleSelector $selector, SplObjectStor
 				continue;
 			}
 
-			// Capture the case where the node itself matches the element.
-			if ($node instanceof DOMElement
+			// jQuery's find() searches descendants only, so a node in the match set is not
+			// a candidate for its own selector. The document element is the exception:
+			// QueryPath seeds the match set with it rather than with the document, so
+			// without this qp($xml)->find('root') could never match.
+			if ($node->parentNode instanceof DOMDocument
 				&& ($element === '*' || $node->tagName === $element)) {
 				$found->offsetSet($node);
 			}

tests/QueryPath/DOMQueryTest.php

@@ -1092,7 +1092,9 @@ public function testPrependTo()
 	public function testBefore()
 	{
 		$file = DATA_FILE;
-		$this->assertEquals(1, qp($file, 'unary')->before('<test/>')->find(':root > test ~ unary')->count());
+		// find() searches descendants, so the search starts from the top of the document —
+		// the same shape as the top() calls below.
+		$this->assertEquals(1, qp($file, 'unary')->before('<test/>')->top()->find(':root > test ~ unary')->count());
 		$this->assertEquals(1, qp($file, 'unary')->before('<test/>')->top('head ~ test')->count());
 		$this->assertEquals(
 			'unary',

tests/QueryPath/FindDescendantOnlyTest.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace QueryPathTests;
+
+/**
+ * find() searches descendants, as jQuery's find() does.
+ *
+ * A node already in the match set is not a candidate for its own selector. The document
+ * element is the one exception, because QueryPath seeds the match set with the document
+ * element rather than with the document node.
+ */
+class FindDescendantOnlyTest extends TestCase
+{
+
+	const XML = '<?xml version="1.0"?><root><a id="a1"><a id="a2"/><b id="b1"/></a></root>';
+
+	public function testFindDoesNotMatchTheNodesItStartsFrom(): void
+	{
+		$a1 = qp(self::XML, '#a1');
+		$this->assertSame('a1', $a1->attr('id'));
+
+		// <a id="a1"> is in the match set, so it is not a candidate: only the nested
+		// <a id="a2"> is found.
+		$found = $a1->find('a');
+		$this->assertCount(1, $found);
+		$this->assertSame('a2', $found->attr('id'));
+	}
+
+	public function testWildcardDoesNotMatchTheNodesItStartsFrom(): void
+	{
+		$ids = [];
+		foreach (qp(self::XML, '#a1')->find('*') as $node) {
+			$ids[] = $node->attr('id');
+		}
+
+		$this->assertSame(['a2', 'b1'], $ids);
+	}
+
+	public function testTheDocumentElementIsStillReachable(): void
+	{
+		// qp() seeds the match set with the document element, which stands in for the
+		// document, so a selector naming it has to keep working.
+		$this->assertCount(1, qp(self::XML)->find('root'));
+		$this->assertSame('root', qp(self::XML)->find('root')->tag());
+
+		$this->assertCount(1, qp(self::XML)->find(':root'));
+	}
+
+	public function testDescendantsOfTheDocumentElementAreStillFound(): void
+	{
+		$this->assertCount(2, qp(self::XML)->find('a'));
+		$this->assertCount(1, qp(self::XML)->find('b'));
+	}
+
+	/**
+	 * filter() is the jQuery-equivalent way to ask whether the nodes in hand match.
+	 */
+	public function testFilterIsTheWayToMatchTheNodesInHand(): void
+	{
+		$this->assertCount(1, qp(self::XML, '#a1')->filter('a'));
+		$this->assertSame('a1', qp(self::XML, '#a1')->filter('a')->attr('id'));
+	}
+}