Support Capybara's finder hints in find_css and find_xpath

CHANGELOG.md

@@ -4,6 +4,9 @@
 - `Driver#downloads` to wait for downloads and list them, files are saved to `Capybara.save_path` [#181]
 
 ### Changed
+- `find_css` and `find_xpath` answer Capybara's finder hints in the call that finds the nodes: nodes that can't hold
+  the text are dropped there, and visibility, styles and position come back in `Node#initial_cache`, so Capybara no
+  longer asks for each node's visibility and text in a round trip of its own [#347]
 
 ### Fixed
 - `Node#drag_to` with `drop_modifiers:` holds the modifiers while moving to the target and sends keydown and keyup for

lib/capybara/cuprite/browser.rb

@@ -94,17 +94,25 @@ def status_code
       end
 
       def find(method, selector)
-        find_all(method, selector)
+        find_with_hints(method, selector).map(&:first)
+      end
+
+      def find_with_hints(method, selector, hints = {})
+        find_all(method, selector, hints)
       end
 
       def property(node, name)
         node.property(name)
       end
 
       def find_within(node, method, selector)
+        find_within_with_hints(node, method, selector).map(&:first)
+      end
+
+      def find_within_with_hints(node, method, selector, hints = {})
         resolved = page.command("DOM.resolveNode", nodeId: node.node_id)
         object_id = resolved.dig("object", "objectId")
-        find_all(method, selector, { "objectId" => object_id })
+        find_all(method, selector, hints, { "objectId" => object_id })
       end
 
       def window_handle
@@ -262,18 +270,21 @@ def all_text(node)
 
       private
 
-      def find_all(method, selector, within = nil)
+      def find_all(method, selector, hints, within = nil)
         # Capybara appends its text-match hint as `(expr)[...]`, but with `exact_text: true` the hint
         # is empty and the result `(expr)[]` is invalid XPath. An empty predicate is never valid, so
         # dropping it can't change a valid selector. Remove once teamcapybara/capybara#2860 is released.
         selector = selector.delete_suffix("[]") if method == :xpath
-        nodes = if within
-                  evaluate("_cuprite.find(arguments[0], arguments[1], arguments[2])", method, selector, within)
-                else
-                  evaluate("_cuprite.find(arguments[0], arguments[1])", method, selector)
-                end
-
-        nodes.select(&:node?)
+        styles = hints[:styles]
+        hints = {
+          visible: hints.fetch(:uses_visibility, false),
+          texts: hints.fetch(:texts, []),
+          styles: (styles.keys.map(&:to_s) if styles.is_a?(Hash)),
+          position: hints.fetch(:position, false)
+        }
+
+        evaluate("_cuprite.findWithHints(...arguments)", *[method, selector, hints, within].compact)
+          .map { |node, cache| [node, cache.transform_keys(&:to_sym)] }
       rescue Ferrum::JavaScriptError => e
         raise InvalidSelector.new(e.response, method, selector) if e.class_name == "InvalidSelector"
 

lib/capybara/cuprite/driver.rb

@@ -76,16 +76,16 @@ def active_element
         Node.new(self, browser.active_element)
       end
 
-      def find_xpath(selector)
-        find(:xpath, selector)
+      def find_xpath(selector, **hints)
+        find(:xpath, selector, **hints)
       end
 
-      def find_css(selector)
-        find(:css, selector)
+      def find_css(selector, **hints)
+        find(:css, selector, **hints)
       end
 
-      def find(method, selector)
-        browser.find(method, selector).map { |native| Node.new(self, native) }
+      def find(method, selector, **hints)
+        browser.find_with_hints(method, selector, hints).map { |native, cache| Node.new(self, native, cache) }
       end
 
       def click(x, y)

lib/capybara/cuprite/javascripts/index.js

@@ -41,6 +41,38 @@
       }
     }
 
+    findWithHints(method, selector, hints, within) {
+      let nodes = this.find(method, selector, within).filter(node => node.nodeType == Node.ELEMENT_NODE);
+
+      if (hints.texts.length > 0) {
+        nodes = nodes.filter(node => this.containsTexts(node, hints.texts, hints.visible));
+      }
+
+      return nodes.map(node => {
+        let cache = {};
+        if (hints.visible) {
+          cache.visible = this.isVisible(node);
+        }
+        if (hints.styles) {
+          let style = window.getComputedStyle(node);
+          cache.style = Object.fromEntries(hints.styles.map(name => [name, style.getPropertyValue(name)]));
+        }
+        if (hints.position) {
+          cache.position = node.getBoundingClientRect().toJSON();
+        }
+        return [node, cache];
+      });
+    }
+
+    // Capybara matches text case sensitively against the visible text, or against all text
+    // with zero width characters removed. The texts hold no whitespace, so a node can only
+    // match when one of these contains every text.
+    containsTexts(node, texts, visible) {
+      let containsAll = content => texts.every(text => content.includes(text));
+      return containsAll(node.textContent.replace(/[\u200b\u200e\u200f]/g, "")) ||
+        (visible && containsAll(this.visibleText(node) || ""));
+    }
+
     parents(node) {
       let nodes = [];
       let parent = node.parentNode;

lib/capybara/cuprite/node.rb

@@ -14,8 +14,8 @@ class Node < Capybara::Driver::Node
 
       DRAG_MODIFIER_ALIASES = { control: :ctrl, command: :meta, cmd: :meta }.freeze
 
-      def initialize(driver, node)
-        super(driver, self)
+      def initialize(driver, node, initial_cache = {})
+        super(driver, self, initial_cache)
         @node = node
       end
 
@@ -40,17 +40,17 @@ def parents
         end
       end
 
-      def find_xpath(selector)
-        find(:xpath, selector)
+      def find_xpath(selector, **hints)
+        find(:xpath, selector, **hints)
       end
 
-      def find_css(selector)
-        find(:css, selector)
+      def find_css(selector, **hints)
+        find(:css, selector, **hints)
       end
 
-      def find(method, selector)
-        command(:find_within, method, selector).map do |node|
-          self.class.new(driver, node)
+      def find(method, selector, **hints)
+        command(:find_within_with_hints, method, selector, hints).map do |node, cache|
+          self.class.new(driver, node, cache)
         end
       end
 

spec/features/session_spec.rb

@@ -556,6 +556,70 @@
       end
     end
 
+    describe "finder hints" do
+      before do
+        @session.visit("/cuprite/find_hints")
+      end
+
+      def ids(nodes)
+        nodes.map { |node| node[:id] }
+      end
+
+      it "answers visibility, styles and position in the initial cache" do
+        shown, hidden = @session.driver.find_css("#shown, #hidden", uses_visibility: true,
+                                                                    styles: { color: "red" },
+                                                                    position: true)
+
+        expect(shown.initial_cache).to include(visible: true, style: { "color" => "rgb(255, 0, 0)" })
+        expect(shown.initial_cache[:position]).to eq(shown.rect)
+        expect(hidden.initial_cache).to include(visible: false)
+      end
+
+      it "leaves the initial cache empty without hints" do
+        expect(@session.driver.find_css("li").map(&:initial_cache)).to all(eq({}))
+      end
+
+      it "keeps only the nodes holding every text" do
+        expect(ids(@session.driver.find_css("li", texts: %w[Shown item]))).to eq(%w[shown])
+        expect(ids(@session.driver.find_css("li", texts: %w[Hidden]))).to eq(%w[hidden])
+        expect(@session.driver.find_css("li", texts: %w[shown])).to be_empty
+      end
+
+      it "matches the visible text only when visibility is asked for" do
+        expect(@session.driver.find_css("li", texts: %w[Splitword])).to be_empty
+        expect(ids(@session.driver.find_css("li", texts: %w[Splitword], uses_visibility: true))).to eq(%w[split])
+      end
+
+      it "finds what Capybara matches on text" do
+        expect(@session.find(:css, "li", text: "Splitword")[:id]).to eq("split")
+        expect(@session.find(:css, "li", text: "Zerowidth", visible: :all)[:id]).to eq("zero_width")
+        expect(@session.find(:css, "li", text: "SHOUTED")[:id]).to eq("shouted")
+        expect(@session.find(:css, "li", text: "Spaced out")[:id]).to eq("spaced")
+        expect(@session.find(:css, "li", text: "Non breaking")[:id]).to eq("non_breaking")
+      end
+
+      it "skips what Capybara doesn't match on text" do
+        expect(@session).to have_no_css("li", text: "shown item")
+        expect(@session).to have_no_css("li", text: "shouted")
+        expect(@session).to have_no_css("li", text: "Zerowidth")
+        expect(@session).to have_no_css("li", text: "Hidden item")
+      end
+
+      it "answers hints within a node" do
+        items = @session.find(:css, "#items")
+        nodes = items.base.find_css("*", texts: %w[Shown], uses_visibility: true)
+
+        expect(ids(nodes)).to eq(%w[shown])
+        expect(nodes.first.initial_cache).to eq(visible: true)
+      end
+
+      it "returns nothing when nothing matches" do
+        expect(@session.driver.find_css("#missing", uses_visibility: true, position: true)).to be_empty
+        expect(@session.driver.find_xpath("//li[@id='missing']", uses_visibility: true)).to be_empty
+        expect(@session.find(:css, "#items").base.find_css("p", texts: %w[Shown])).to be_empty
+      end
+    end
+
     describe "Node#shadow_root" do
       it "produces error messages when failing" do
         @session.visit("/with_shadow")

spec/support/views/find_hints.erb

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <body>
+    <ul id="items">
+      <li id="shown" style="color: rgb(255, 0, 0)">Shown item</li>
+      <li id="hidden" style="display: none">Hidden item</li>
+      <li id="split">Split<span style="display: none">hidden</span>word</li>
+      <li id="zero_width">Zero&#8203;width</li>
+      <li id="shouted" style="text-transform: uppercase">shouted</li>
+      <li id="spaced">Spaced
+        out</li>
+      <li id="non_breaking">Non&nbsp;breaking</li>
+    </ul>
+    <p id="outside">Shown item</p>
+  </body>
+</html>