capybara-lightpanda 0.14.1 → 0.15.0

data/lib/capybara/lightpanda/client/web_socket.rb

@@ -26,11 +26,18 @@ module Capybara
           connect
         end
 
-        def send_message(message)
+        # `timeout` bounds how long the browser may go without taking any of
+        # the frame's bytes (see #write); nil falls back to options.timeout.
+        def send_message(message, timeout: nil)
           raise DeadBrowserError, "WebSocket is not open" unless @status == :open
 
           @logger&.puts("\n\n▶ #{@logger.elapsed_time} #{message}")
-          @driver_mutex.synchronize { @driver.text(message) }
+          @driver_mutex.synchronize do
+            @write_timeout = timeout
+            @driver.text(message)
+          ensure
+            @write_timeout = nil
+          end
         end
 
         # The socket is closed even when the connection is already dead. A
@@ -53,8 +60,25 @@ module Capybara
           @status == :closed || @status == :error
         end
 
+        # Called by websocket-driver, always under @driver_mutex. A browser
+        # that stops reading (hung, stopped, or a page stuck in a sync JS loop
+        # on Lightpanda's single thread) would block a plain write forever
+        # once the frame outgrows the socket buffers, holding the lock that
+        # every other command, the reader's parse and #close need — and the
+        # command timeout only starts after the write returns. So the write
+        # gives up once the browser takes no byte for the timeout; the wait
+        # restarts on every partial write, so a slow but moving peer is fine
+        # (ferrum #644). Close and pong frames have no command timeout and
+        # fall back to options.timeout rather than waiting forever.
         def write(data)
-          @socket.write(data)
+          until data.empty?
+            written = @socket.write_nonblock(data, exception: false)
+            if written.is_a?(Integer)
+              data = data.byteslice(written..)
+            elsif !wait_for_socket(written)
+              abandon_stalled_write
+            end
+          end
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           mark_dead
         end
@@ -71,6 +95,21 @@ module Capybara
 
         private
 
+        def wait_for_socket(state)
+          timeout = @write_timeout || @options.timeout
+          state == :wait_readable ? @socket.wait_readable(timeout) : @socket.wait_writable(timeout)
+        end
+
+        # The frame was cut off midway, so the connection can't be reused:
+        # mark it dead (the reader and message threads stop, pending commands
+        # are released) and close the socket.
+        def abandon_stalled_write
+          timeout = @write_timeout || @options.timeout
+          mark_dead(:error)
+          close_socket
+          raise DeadBrowserError, "Browser accepted no data for #{timeout}s and is likely stuck; connection closed"
+        end
+
         def close_socket
           @socket&.close unless @socket.nil? || @socket.closed?
         rescue IOError, SystemCallError
@@ -175,12 +214,31 @@ module Capybara
           raise TimeoutError, "WebSocket handshake timed out after #{@options.handshake_timeout}s"
         end
 
+        # A JS string can hold a lone UTF-16 surrogate ("😀".slice(0, 1));
+        # Lightpanda escapes it as `\ud83d`, which Ruby's json rejects.
+        # Dropping that frame left its command waiting out the full timeout,
+        # so retry once with every lone surrogate replaced by U+FFFD — what
+        # Chrome and Ferrum (#648) hand back for the same value.
         def parse_message(data)
           JSON.parse(data, max_nesting: false)
         rescue JSON::ParserError => e
-          warn_parse_failure(e.message)
+          begin
+            JSON.parse(replace_lone_surrogates(data), max_nesting: false)
+          rescue JSON::ParserError
+            warn_parse_failure(e.message)
+
+            nil
+          end
+        end
+
+        # Alternation order matters: a valid lead+trail pair is consumed
+        # whole, then a lone surrogate, then any other escape (`\\`, `\"`,
+        # a non-surrogate `\uXXXX`) is skipped as-is — scanning left to
+        # right so `\\ud800` (an escaped backslash, then text) survives.
+        SURROGATE_ESCAPE = /\\u[dD][89abAB]\h{2}\\u[dD][c-fC-F]\h{2}|(\\u[dD][89a-fA-F]\h{2})|\\./m
 
-          nil
+        def replace_lone_surrogates(data)
+          data.gsub(SURROGATE_ESCAPE) { |escape| Regexp.last_match(1) ? "\\uFFFD" : escape }
         end
 
         # Dedupe identical parse-failure warnings per WebSocket instance.

data/lib/capybara/lightpanda/client.rb

@@ -22,18 +22,18 @@ module Capybara
 
       def command(method, params = {}, async: false, session_id: nil, timeout: nil)
         message = build_message(method, params, session_id: session_id)
+        effective_timeout = timeout || @options.timeout
 
         if async
-          @ws.send_message(JSON.generate(message))
+          @ws.send_message(JSON.generate(message), timeout: effective_timeout)
           return true
         end
 
         pending = Concurrent::IVar.new
         @pendings[message[:id]] = pending
 
-        @ws.send_message(JSON.generate(message))
+        @ws.send_message(JSON.generate(message), timeout: effective_timeout)
 
-        effective_timeout = timeout || @options.timeout
         response = pending.value!(effective_timeout)
 
         if response.nil?
@@ -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/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;
@@ -56,13 +55,22 @@ function isObscured(el) {
   var hit = doc.elementFromPoint(cx, cy);
   if (!hit) return true;
   if (hit === el) return false;
-  return !el.contains(hit);
+  if (el.contains(hit)) return false;
+  // A hit inside a shadow tree is retargeted to its host, and there is no
+  // ShadowRoot.elementFromPoint to look further, so landing on one of el's own
+  // hosts is the best "not obscured" answer available.
+  var root = el.getRootNode ? el.getRootNode() : doc;
+  while (root && root !== doc && root.host) {
+    if (hit === root.host) return false;
+    root = root.host.getRootNode();
+  }
+  return true;
 }
 
 // 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 +161,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