capybara-lightpanda 0.14.2 → 0.16.0

data/lib/capybara/lightpanda/client.rb

@@ -149,7 +149,10 @@ module Capybara
         message = error["message"]
 
         case message
-        when /No node with given id found/i
+        # A node from a previous document passed as an *argument* (bound as
+        # `this` it answers "Cannot find context" below). Ferrum #647.
+        when /No node with given id found/i,
+             /Argument should belong to the same JavaScript world as target object/i
           raise NodeNotFoundError, message
         when /Cannot find context with specified id/i,
              /Execution context was destroyed/i,

data/lib/capybara/lightpanda/cookies.rb

@@ -76,7 +76,7 @@ module Capybara
       def get(name)
         find { |cookie| cookie.name == name }
       end
-      # Ferrum/Cuprite spelling: `browser.cookies["session_id"]`.
+      # Ferrum spelling: `browser.cookies["session_id"]`.
       alias [] get
 
       # Returns whether the browser accepted the cookie (ferrum parity).

data/lib/capybara/lightpanda/downloads.rb

@@ -12,10 +12,10 @@ module Capybara
     # `Browser.downloadProgress`. We mirror those into a completed-files list +
     # a blocking `wait`, the way ferrum's Downloads does.
     #
-    # IMPORTANT: the trigger is `Content-Disposition: attachment`, NOT MIME
-    # type. A `text/csv` (or any) response without that header is rendered as a
-    # normal navigation, not downloaded — which is why Capybara's MIME-triggered
-    # `:download` shared spec stays in capybara_skip.
+    # Navigation downloads require Content-Disposition: attachment, not just a
+    # MIME type. New browsers also honor an anchor's download attribute (build
+    # 11097 / 1.1 release line); Node#click lets that native activation finish.
+    # Capybara's MIME-only :download shared spec still stays in capybara_skip.
     #
     # Structure deliberately mirrors Network (same browser ref, same mutex +
     # subscribe/unsubscribe lifecycle, same reset-after-disposeBrowserContext

data/lib/capybara/lightpanda/driver.rb

@@ -72,20 +72,20 @@ module Capybara
         oid && build_node(oid)
       end
 
-      # Capybara's Session#send_keys routes to Driver#send_keys; Cuprite's pattern
-      # is to fan that out to whatever element currently has focus.
+      # Capybara's Session#send_keys routes to Driver#send_keys; fan that out
+      # to whatever element currently has focus.
       def send_keys(*keys)
         active_element&.send_keys(*keys)
       end
 
-      def find_xpath(selector)
-        object_ids = browser.find("xpath", selector)
-        object_ids.map { |oid| build_node(oid) }
+      # Accepting `**hints` is what makes Capybara send them (it checks the
+      # arity); Node.hint_spec turns them into the answers the find returns.
+      def find_xpath(selector, **hints)
+        browser.find_hinted("xpath", selector, Node.hint_spec(**hints)).map { |oid, cache| build_node(oid, cache) }
       end
 
-      def find_css(selector)
-        object_ids = browser.find("css", selector)
-        object_ids.map { |oid| build_node(oid) }
+      def find_css(selector, **hints)
+        browser.find_hinted("css", selector, Node.hint_spec(**hints)).map { |oid, cache| build_node(oid, cache) }
       end
 
       # Inside `within_frame` these run in the frame's document, as in Chrome.
@@ -107,7 +107,7 @@ module Capybara
       # -- Network Inspection --
 
       # Network tracker (lazily auto-enabled). Exposes `traffic`, `clear`,
-      # `wait_for_idle`, header overrides, etc. Cuprite parity.
+      # `wait_for_idle`, header overrides, etc.
       def network
         browser.network
       end
@@ -124,7 +124,7 @@ module Capybara
       # Files downloaded since the session started (absolute paths). Capture is
       # on whenever a destination exists (the :save_path driver option, else
       # Capybara.save_path) and the server sends `Content-Disposition:
-      # attachment`. Ferrum/Cuprite expose downloads on the driver too.
+      # attachment`. Ferrum exposes downloads on its browser too.
 
       def downloads
         browser.downloads.files
@@ -286,18 +286,18 @@ module Capybara
       end
 
       # capybara-screenshot's fallback for unregistered drivers calls
-      # `driver.render(path)` (the Cuprite/Ferrum spelling). Without the alias
-      # every failed test in a capybara-screenshot suite logged
-      # "Screenshot could not be saved: undefined method 'render'".
+      # `driver.render(path)`. Without the alias every failed test in a
+      # capybara-screenshot suite logged "Screenshot could not be saved:
+      # undefined method 'render'".
       alias render save_screenshot
 
-      # -- Headers (Cuprite-compatible driver surface) --
+      # -- Headers (driver surface) --
       # Delegates to Network, which lazily enables the Network domain. The
       # overrides do NOT survive reset!: disposing the BrowserContext takes
       # setExtraHTTPHeaders with it, so Network#reset drops its cached copy
       # rather than report headers the browser stopped sending (pinned by
-      # network_test.rb "clears extra_headers"). Cuprite exposes these on the
-      # driver, and real suites call them there (page.driver.headers = ...).
+      # network_test.rb "clears extra_headers"). Real suites call these on the
+      # driver (page.driver.headers = ...).
 
       def headers
         browser.network.extra_headers
@@ -313,9 +313,9 @@ module Capybara
 
       # -- Lifecycle --
 
-      # Thin Cuprite-style wrapper. The interesting work — disposing the
-      # BrowserContext (cookies, storage, all targets) and starting a fresh
-      # one — happens in Browser#reset.
+      # Thin wrapper. The interesting work — disposing the BrowserContext
+      # (cookies, storage, all targets) and starting a fresh one — happens in
+      # Browser#reset.
       #
       # Rescue is the gem hierarchy plus raw IO escapees only — NOT
       # StandardError: reset! runs between every test, so a blanket rescue
@@ -345,11 +345,10 @@ module Capybara
         true
       end
 
-      # Expanded error list for Capybara retry logic (Cuprite pattern).
-      # MouseEventFailed is in Cuprite's list, but Lightpanda has no
-      # rendering engine and the gem dispatches clicks through JS — the
-      # underlying CDP Input.dispatchMouseEvent path doesn't run, so
-      # MouseEventFailed is never raised.
+      # Expanded error list for Capybara retry logic. MouseEventFailed is left
+      # out: Lightpanda has no rendering engine and the gem dispatches clicks
+      # through JS — the underlying CDP Input.dispatchMouseEvent path doesn't
+      # run, so MouseEventFailed is never raised.
       def invalid_element_errors
         [
           NodeNotFoundError,
@@ -374,8 +373,8 @@ module Capybara
 
       # A node found while a frame is switched to lives in that frame's
       # document, which Node#call checks for a frame navigation.
-      def build_node(oid)
-        Node.new(self, oid, frame_scoped: browser.frame_stack.any?)
+      def build_node(oid, initial_cache = {})
+        Node.new(self, oid, initial_cache, frame_scoped: browser.frame_stack.any?)
       end
 
       # Every window method takes a handle because Capybara's Window objects
@@ -391,7 +390,7 @@ module Capybara
 
       # Unwrap arguments before sending to the browser. Capybara::Node::Element wraps
       # our Lightpanda::Node — pull `.base` out so `serialize_argument` can build
-      # `{objectId: …}` for the CDP payload. Cuprite's `native_args` pattern.
+      # `{objectId: …}` for the CDP payload.
       def native_args(args)
         args.map { |a| a.is_a?(Capybara::Node::Element) ? a.base : a }
       end
@@ -399,7 +398,7 @@ module Capybara
       # Lightpanda's `Network.setCookie` requires either `domain` or `url`
       # (storage.zig → Cookie.parseDomain). When the caller doesn't supply one,
       # use the host of the current page if any, else `Capybara.app_host`,
-      # else loopback. Cuprite parity — lets pre-visit cookie setup just work.
+      # else loopback. Lets pre-visit cookie setup just work.
       def default_domain
         candidate = (@started && safe_uri_host(browser.current_url)) ||
                     safe_uri_host(Capybara.app_host)

data/lib/capybara/lightpanda/errors.rb

@@ -106,11 +106,11 @@ module Capybara
       end
     end
 
-    # --- Cuprite/Ferrum drop-in compatibility surface ---
+    # --- Drop-in compatibility surface ---
     # This gem never raises the three classes below (no coordinate-based
     # mouse path, no multi-page API, no page-status tracking). They mirror
-    # the peer taxonomy (Cuprite's MouseEventFailed, Ferrum's
-    # NoSuchPageError/StatusError) so suites migrating from those drivers
+    # the error taxonomy of other Capybara CDP drivers (MouseEventFailed, plus
+    # Ferrum's NoSuchPageError/StatusError) so suites migrating from them
     # don't NameError on rescue lists that reference them.
     class MouseEventFailed < BrowserError
       attr_reader :node, :selector, :position

data/lib/capybara/lightpanda/javascripts/attach.js

@@ -13,5 +13,6 @@ window._lightpanda = {
   isDisabled: isDisabled,
   isContentEditable: isContentEditable,
   pointerFocusTarget: pointerFocusTarget,
-  visibleText: visibleText
+  visibleText: visibleText,
+  findHints: findHints
 };

data/lib/capybara/lightpanda/javascripts/predicates.js

@@ -19,12 +19,11 @@
 // External `<link rel=stylesheet>` ARE fetched and applied — the gem
 // always passes `--load-resources stylesheet` (Lightpanda PR #2487,
 // guaranteed by the build floor) — so stylesheet-driven `display:none`
-// participates in this check. The remaining gap is viewport emulation:
-// `@media` rules and `matchMedia()` evaluate against the hardcoded
-// 1920×1080 viewport (no resize), so visibility gated on a non-desktop
-// viewport — e.g. a mobile-only CTA under `@media (max-width: …)` —
-// resolves like desktop Chrome at 1920×1080. Keep those specs on a
-// full-layout driver (README's dual-driver setup).
+// participates in this check. `@media` rules evaluate against the
+// emulated viewport (`window_size`, 1920×1080 by default), so a
+// mobile-only CTA under `@media (max-width: …)` needs a narrow
+// `window_size` — or `resize_to` then `visit`, since a loaded document's
+// cascade doesn't re-resolve on resize.
 function isVisible(el) {
   if (!el || el.nodeType !== 1) return false;
   var win = el.ownerDocument.defaultView || window;
@@ -55,14 +54,30 @@ function isObscured(el) {
   if (cx < 0 || cy < 0 || cx > w || cy > h) return true;
   var hit = doc.elementFromPoint(cx, cy);
   if (!hit) return true;
-  if (hit === el) return false;
-  return !el.contains(hit);
+  // Document hit testing retargets a shadow child to its outermost host.
+  // Check each enclosing shadow tree from the outside in: an inner root must
+  // never let us see through an overlay covering its host in an outer root.
+  var roots = [], root = el.getRootNode ? el.getRootNode() : doc;
+  while (root && root !== doc && root.host) {
+    roots.push(root);
+    root = root.host.getRootNode();
+  }
+  for (var i = roots.length - 1; i >= 0; i--) {
+    root = roots[i];
+    if (hit !== root.host) break;
+    // Older supported builds have no shadow hit testing. A hit on our own
+    // host remains the best available evidence that the child is actionable.
+    if (typeof root.elementFromPoint !== 'function') return false;
+    hit = root.elementFromPoint(cx, cy);
+    if (!hit) return true;
+  }
+  return hit !== el && !el.contains(hit);
 }
 
 // Capybara's `Node#disabled?` is more permissive than CSS `:disabled`:
 // an `<option>` inside a disabled `<select>` or a disabled `<fieldset>`
 // is reported as disabled, even though those don't match CSS `:disabled`
-// per the HTML spec. Mirrors Cuprite's behavior so the shared specs pass.
+// per the HTML spec — the Capybara shared specs expect them disabled.
 function isDisabled(el) {
   if (el.matches && el.matches(':disabled')) return true;
   if ((el.tagName || '').toUpperCase() === 'OPTION') {
@@ -153,3 +168,60 @@ function visibleText(el) {
   }
   return out;
 }
+
+// Capture intrinsics before page scripts can replace them. Array operations use
+// indexed loops: an overridden map must never detach cache rows from node IDs.
+var hintStringify = JSON.stringify;
+var hintLowerCase = Function.prototype.call.bind(String.prototype.toLowerCase);
+
+// Capybara keeps Result candidates for lazy enumeration, possibly after the DOM
+// changes. Only immutable tag names belong in initial_cache; mutable visibility,
+// geometry and styles must be read live. Text hints are a conservative prefilter.
+function findHints(nodes, spec) {
+  // Bound eager subtree text walks: nested candidates otherwise make first()
+  // quadratic even though Capybara would inspect only the first candidate.
+  if (nodes.length > 512) return nodes;
+  try {
+    var texts = spec.texts || [];
+    var needles = [];
+    for (var i = 0; i < texts.length; i++) {
+      // Ruby splits ASCII whitespace, not every Unicode separator. Unicode
+      // casing can also depend on context (Greek final sigma). Fail open.
+      if (/[^\x00-\x7F]/.test(texts[i])) return nodes;
+      needles[i] = hintLowerCase(texts[i]);
+    }
+    var kept = [];
+    var hints = [];
+    for (var j = 0; j < nodes.length; j++) {
+      var el = nodes[j];
+      var matches = true;
+      if (needles.length) {
+        var all = el.textContent || '';
+        var visible = visibleText(el) || '';
+        // The driver's all_text and visible_text normalize Unicode differently.
+        // Retain such candidates for Capybara's authoritative text comparison.
+        if (!/[^\x00-\x7F]/.test(all + visible)) {
+          all = hintLowerCase(all);
+          visible = hintLowerCase(visible);
+          for (var k = 0; k < needles.length; k++) {
+            if (all.indexOf(needles[k]) === -1 && visible.indexOf(needles[k]) === -1) {
+              matches = false;
+              break;
+            }
+          }
+        }
+      }
+      if (matches) {
+        hints[kept.length] = { tag_name: el.nodeType === 11 ? 'ShadowRoot' :
+          (el.tagName ? hintLowerCase(el.tagName) : '') };
+        kept[kept.length] = el;
+      }
+    }
+    // Publish only after every read succeeds. Any exception returns the exact
+    // original array, without partial filtering or partially constructed hints.
+    kept.__lightpandaHints = hintStringify(hints);
+    return kept;
+  } catch (e) {
+    return nodes;
+  }
+}

data/lib/capybara/lightpanda/keyboard.rb

@@ -97,6 +97,11 @@ module Capybara
       # so JS keydown handlers see the modifier event; CDP's `rawKeyDown` is
       # documented as "no JS keyDown event is generated" and would hide the
       # modifier from listeners that count keydown events.
+      #
+      # Anything that is not a Symbol or an Array is typed as its `to_s`, as
+      # Selenium's `Keys.encode` does: `send_keys [1, :tab]` types "1", and
+      # `nil` types nothing. Without it an Integer was dropped silently and
+      # only the Tab went out.
       def type(*keys)
         active_mods = []
         keys.each do |key|
@@ -107,10 +112,10 @@ module Capybara
             else
               dispatch_key_with_mods(key, active_mods)
             end
-          when String
-            key.each_char { |char| dispatch_char_with_mods(char, active_mods) }
           when Array
             type_with_modifiers(key)
+          else
+            type_text(key, active_mods)
           end
         end
         release_modifiers(active_mods)
@@ -163,14 +168,19 @@ module Capybara
         active_mods = []
         modifiers.each { |m| press_modifier(m, active_mods) }
         rest.each do |key|
-          case key
-          when Symbol then dispatch_key_with_mods(key, active_mods)
-          when String then key.each_char { |char| dispatch_char_with_mods(char, active_mods) }
+          if key.is_a?(Symbol)
+            dispatch_key_with_mods(key, active_mods)
+          else
+            type_text(key, active_mods)
           end
         end
         release_modifiers(active_mods)
       end
 
+      def type_text(key, active_mods)
+        key.to_s.each_char { |char| dispatch_char_with_mods(char, active_mods) }
+      end
+
       # A chord with Ctrl or Meta is a command, not text: Chrome inserts
       # nothing for Ctrl+A, it selects. Since upstream #3542 (build 9580)
       # Lightpanda inserts whatever the keyDown's `text` carries, so sending

data/lib/capybara/lightpanda/network.rb

@@ -92,7 +92,7 @@ module Capybara
 
       # Setting extra headers also lazily enables the Network domain. Without
       # this, headers were silently ignored until the caller separately ran
-      # `network.enable` (or `wait_for_network_idle`). Cuprite/Ferrum parity.
+      # `network.enable` (or `wait_for_network_idle`).
       def headers=(headers)
         enable
         @extra_headers = headers