capybara-lightpanda 0.8.0 → 0.10.0

data/lib/capybara/lightpanda/browser/finder.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # Element finding in the three dispatch contexts (document, node-
+      # scoped, iframe) plus the shared XPath/CSS find fragments and
+      # InvalidSelector translation.
+      module Finder
+        # Find elements in the current context (top frame or active frame).
+        # Returns an array of remote object ID strings.
+        def find(method, selector)
+          if @frame_stack.empty?
+            find_in_document(method, selector)
+          else
+            find_in_frame(method, selector)
+          end
+        end
+
+        # Find child elements within a specific node.
+        # Returns an array of remote object ID strings.
+        #
+        # Wrapped in `with_default_context_wait` so a click that triggered a
+        # navigation immediately before the find (e.g. a fill_in following a
+        # link that mutated the DOM) doesn't race against
+        # `Runtime.executionContextCreated` and surface as
+        # `NoExecutionContextError`. `find_in_document` and `find_in_frame`
+        # already use the same wrapper; `find_within` was the odd one out.
+        def find_within(remote_object_id, method, selector)
+          with_default_context_wait do
+            result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, return_by_value: false)
+            extract_node_object_ids(result)
+          end
+        rescue JavaScriptError => e
+          raise_invalid_selector(e, method, selector)
+        end
+
+        # Ancestor chain of `remote_object_id` from parentNode up to (but
+        # excluding) `document`, returned as an array of remote object IDs.
+        # Mirrors Cuprite's JS `parents` helper. Same `with_default_context_wait`
+        # wrapping as `find_within` — same race window applies.
+        def parents_of(remote_object_id)
+          with_default_context_wait do
+            result = call_function_on(remote_object_id, PARENTS_JS, return_by_value: false)
+            extract_node_object_ids(result)
+          end
+        end
+
+        private
+
+        # Sentinel string thrown from FIND_*_JS when querySelectorAll rejects a
+        # malformed selector, so the Ruby side can convert JavaScriptError into
+        # Capybara::Lightpanda::InvalidSelector. Cuprite uses a JS subclass for
+        # the same purpose; a plain prefixed string keeps our inline JS simple.
+        INVALID_SELECTOR_MARKER = "LIGHTPANDA_INVALID_SELECTOR:"
+
+        # The find algorithms exist in three dispatch contexts — element-scoped
+        # (FIND_WITHIN_JS), iframe-scoped (FIND_IN_FRAME_JS), and document-scoped
+        # (find_in_document's Runtime.evaluate fast path) — that differ only in
+        # how the document/root/selector expressions are derived. Each algorithm
+        # is defined ONCE here and instantiated per context via format(), so a
+        # fix (e.g. a new XPath error case) can't silently miss a copy.
+        #
+        # XPath routes through native `Document.evaluate` + `XPathResult`
+        # (Lightpanda PR #2305, in nightly >=6109); on parse error we return
+        # [] silently to match Capybara's internal XPath generator, which
+        # sometimes produces selectors with empty trailing predicates like
+        # `(...)[]` that native rejects but `has_element?` expects to behave
+        # as "not found" rather than raise InvalidSelector.
+        # `XPathResult.ORDERED_NODE_SNAPSHOT_TYPE` is `7` in the spec — inlined
+        # so the JS doesn't depend on the enum being defined as a constant.
+        XPATH_FIND_FRAGMENT = <<~JS
+          try {
+            var r = %<doc>s.evaluate(%<selector>s, %<root>s, null, 7, null);
+            var nodes = [];
+            for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+            return nodes;
+          } catch(e) { return []; }
+        JS
+
+        # For CSS, any throw from querySelectorAll means the selector is
+        # malformed — re-throw with the marker prefix so Ruby converts to
+        # InvalidSelector.
+        CSS_FIND_FRAGMENT = <<~JS.freeze
+          try { return Array.from(%<target>s.querySelectorAll(%<selector>s)); }
+          catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + %<selector>s); }
+        JS
+        private_constant :XPATH_FIND_FRAGMENT, :CSS_FIND_FRAGMENT
+
+        # JS function for finding elements within a node.
+        # Works in any execution context (top frame or iframe).
+        FIND_WITHIN_JS = <<~JS.freeze
+          function(method, selector) {
+            if (method === 'xpath') {
+              #{format(XPATH_FIND_FRAGMENT, doc: 'this.ownerDocument', root: 'this', selector: 'selector')}
+            }
+            #{format(CSS_FIND_FRAGMENT, target: 'this', selector: 'selector')}
+          }
+        JS
+        private_constant :FIND_WITHIN_JS
+
+        # JS function for finding elements in an iframe's contentDocument.
+        FIND_IN_FRAME_JS = <<~JS.freeze
+          function(method, selector) {
+            var doc;
+            try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
+            if (!doc) return [];
+            if (method === 'xpath') {
+              #{format(XPATH_FIND_FRAGMENT, doc: 'doc', root: 'doc', selector: 'selector')}
+            }
+            #{format(CSS_FIND_FRAGMENT, target: 'doc', selector: 'selector')}
+          }
+        JS
+        private_constant :FIND_IN_FRAME_JS
+
+        # Walks `parentNode` from `this` up to (but excluding) `document`,
+        # returning the chain as a JS array. Each entry is an element node so
+        # `extract_node_object_ids` can wrap them as Lightpanda::Nodes.
+        PARENTS_JS = <<~JS
+          function() {
+            var nodes = [];
+            var p = this.parentNode;
+            while (p && p !== this.ownerDocument) {
+              nodes.push(p);
+              p = p.parentNode;
+            }
+            return nodes;
+          }
+        JS
+        private_constant :PARENTS_JS
+
+        def find_in_document(method, selector)
+          with_default_context_wait do
+            # Coerce Symbol selectors (e.g. Capybara warning path lets `have_css(:p)`
+            # through) to a string before quoting. Symbol#inspect returns `:p`,
+            # which would inject a bare token into the JS source.
+            selector_literal = selector.to_s.inspect
+            # Same fragments as FIND_WITHIN_JS/FIND_IN_FRAME_JS, instantiated
+            # with the selector embedded as a literal: this hot path keeps its
+            # single Runtime.evaluate round-trip (no document-handle resolution).
+            fragment = if method == "xpath"
+                         format(XPATH_FIND_FRAGMENT, doc: "document", root: "document", selector: selector_literal)
+                       else
+                         format(CSS_FIND_FRAGMENT, target: "document", selector: selector_literal)
+                       end
+            result = evaluate_with_ref("(function() { #{fragment} })()")
+            extract_node_object_ids(result)
+          end
+        rescue JavaScriptError => e
+          raise_invalid_selector(e, method, selector)
+        end
+
+        def find_in_frame(method, selector)
+          with_default_context_wait do
+            frame_node = @frame_stack.last
+            result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector,
+                                      return_by_value: false)
+            extract_node_object_ids(result)
+          end
+        rescue JavaScriptError => e
+          raise_invalid_selector(e, method, selector)
+        end
+
+        def raise_invalid_selector(js_error, method, selector)
+          if js_error.message.include?(INVALID_SELECTOR_MARKER)
+            raise InvalidSelector.new("Invalid #{method} selector: #{selector.inspect}", method, selector)
+          end
+
+          raise js_error
+        end
+
+        # Extract individual node objectIds from a remote array reference.
+        # `ensure release_object` so the outer array handle is freed even when
+        # property walking raises — without this, a transient CDP error during
+        # property enumeration leaks one V8 handle per failed find call.
+        def extract_node_object_ids(result)
+          return [] unless result && result["objectId"]
+
+          outer_id = result["objectId"]
+          begin
+            props = get_object_properties(outer_id)
+            properties = props["result"] || []
+            properties
+              .select { |p| p["name"] =~ /\A\d+\z/ }
+              .sort_by { |p| p["name"].to_i }
+              .filter_map { |p| p.dig("value", "objectId") }
+          rescue Error
+            []
+          ensure
+            release_object(outer_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/browser/modals.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # JS dialog handling via Lightpanda's LP.handleJavaScriptDialog
+      # pre-arm model (PR #2261): accept/dismiss are sent BEFORE the
+      # triggering action; Page.javascriptDialogOpening supplies the text.
+      module Modals
+        # -- Modal/Dialog Support --
+        # Lightpanda's JS dialogs (alert/confirm/prompt) are driven via the
+        # `LP.handleJavaScriptDialog` pre-arm model (PR #2261, nightly ≥5900):
+        # the client sends `LP.handleJavaScriptDialog {accept, promptText}`
+        # BEFORE the action that triggers the dialog, and the response is
+        # consumed when the dialog opens. `Page.javascriptDialogOpening` still
+        # fires, so we capture the message text for `find_modal`. Single-shot:
+        # `pending_dialog_response` is one slot, so a second pre-arm before
+        # the first dialog opens overwrites the first.
+
+        def prepare_modals
+          return if @modal_handler_installed
+
+          enable_page_events
+
+          on("Page.javascriptDialogOpening") do |params|
+            entry = { type: params["type"], message: params["message"] }
+            @modal_messages_mutex.synchronize do
+              @modal_messages << entry
+              # The pre-arm slot is single-shot on both sides: Lightpanda
+              # consumes its stashed response on this dialog, so we consume
+              # ours. No pre-arm in flight means Lightpanda just applied its
+              # silent default — remember it for the main thread; raising here
+              # would only die inside the subscriber.
+              if @modal_armed
+                @modal_armed = false
+              else
+                @unhandled_modal ||= entry
+              end
+            end
+          end
+
+          @modal_handler_installed = true
+        end
+
+        def accept_modal(_type, text: nil)
+          prepare_modals
+          params = { accept: true }
+          params[:promptText] = text if text
+          arm_modal { page_command("LP.handleJavaScriptDialog", **params) }
+        end
+
+        def dismiss_modal(_type)
+          prepare_modals
+          arm_modal { page_command("LP.handleJavaScriptDialog", accept: false) }
+        end
+
+        # Surface a dialog that opened with no pre-arm. Called from the main
+        # thread after every action that can open one (Browser#wait_for_idle,
+        # #go_to). Warns by default; raises when the driver was built with
+        # `raise_on_unhandled_modal: true` (Cuprite's option name). Either way
+        # the dialog is already gone — Lightpanda's default resolved it.
+        def check_unhandled_modal!
+          entry = @modal_messages_mutex.synchronize do
+            e = @unhandled_modal
+            @unhandled_modal = nil
+            e
+          end
+          return unless entry
+
+          message = unhandled_modal_message(entry)
+          raise UnhandledModalError, message if @options.raise_on_unhandled_modal
+
+          warn "[capybara-lightpanda] #{message}"
+        end
+
+        # `type` is accepted for the error message only: like Selenium (where
+        # alert/confirm are indistinguishable) and Cuprite (whose dialog handler
+        # accepts whatever fires), we deliberately do NOT reject a dialog whose
+        # reported type differs from the one Capybara asked for. Real suites
+        # wrap `data-confirm` deletes in `accept_alert` (e.g. solidus admin) and
+        # expect it to work; only the message text is matched.
+        def find_modal(type, text: nil, wait: options.timeout)
+          regexp = text.is_a?(Regexp) ? text : (text && Regexp.new(Regexp.escape(text.to_s)))
+          last_seen_message = nil
+          claimed = nil
+          Utils::Wait.until(timeout: wait, interval: 0.05) do
+            claimed = pop_modal_message(regexp)
+            next true if claimed
+
+            last_seen_message = peek_last_modal_message || last_seen_message
+            false
+          end
+          claimed[:message]
+        rescue TimeoutError
+          raise_modal_not_found(type, text, last_seen_message)
+        end
+
+        private
+
+        def arm_modal
+          @modal_messages_mutex.synchronize { @modal_armed = true }
+          yield
+        end
+
+        LIGHTPANDA_DIALOG_DEFAULTS = {
+          "confirm" => "cancelled it",
+          "prompt" => "answered null",
+          "beforeunload" => "cancelled it",
+        }.freeze
+        private_constant :LIGHTPANDA_DIALOG_DEFAULTS
+
+        def unhandled_modal_message(entry)
+          with_text = entry[:message] ? " with text `#{entry[:message]}`" : ""
+          default = LIGHTPANDA_DIALOG_DEFAULTS.fetch(entry[:type].to_s, "dismissed it")
+          "A #{entry[:type]} dialog#{with_text} opened, but the action was not wrapped in " \
+            "accept_alert / accept_confirm / dismiss_confirm / accept_prompt / dismiss_prompt " \
+            "— Lightpanda #{default} by default"
+        end
+
+        # Pop the first queued dialog whose message matches the requested
+        # pattern (any dialog when `regexp` is nil). Returns the entry or nil.
+        # Serialized with the message-thread writer.
+        def pop_modal_message(regexp)
+          @modal_messages_mutex.synchronize do
+            match = @modal_messages.find do |m|
+              regexp.nil? || m[:message].to_s.match?(regexp)
+            end
+            @modal_messages.delete(match) if match
+            match
+          end
+        end
+
+        # Most recent dialog message of any type, for diagnostics.
+        def peek_last_modal_message
+          @modal_messages_mutex.synchronize { @modal_messages.last&.dig(:message) }
+        end
+
+        def raise_modal_not_found(type, text, last_seen_message)
+          if last_seen_message
+            raise Capybara::ModalNotFound,
+                  "Unable to find #{type} modal with #{text} - found '#{last_seen_message}' instead."
+          end
+          raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}"
+        end
+
+        private :prepare_modals
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/browser/navigation.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # Navigation lifecycle: go_to / back / forward / refresh and the
+      # Page.loadEventFired + readyState-polling machinery behind them
+      # (the polling fallback is load-bearing — see CLAUDE.md).
+      module Navigation
+        # Navigation with readyState fallback.
+        #
+        # Lightpanda may never fire Page.loadEventFired on complex JS pages
+        # (lightpanda-io/browser#1801, #1832). When the event times out,
+        # we poll document.readyState as a fallback.
+        #
+        # Page.navigate is sent asynchronously because Lightpanda may not
+        # return the command result until the page is fully loaded (unlike
+        # Chrome which returns immediately with frameId/loaderId). If we
+        # waited synchronously, the readyState fallback would never be
+        # reached on pages that fail to fully load.
+        #
+        # Uses a single shared deadline so the worst-case wait is 1x timeout,
+        # not 2x (lightpanda-io/browser#1849).
+        def go_to(url, wait: true)
+          enable_page_events
+
+          if wait
+            wait_for_page_load(url)
+          else
+            page_command("Page.navigate", url: url)
+          end
+          check_unhandled_modal!
+        end
+        alias goto go_to
+
+        def back
+          wait_for_navigation { navigate_history(-1) }
+        end
+
+        def forward
+          wait_for_navigation { navigate_history(+1) }
+        end
+
+        def refresh
+          wait_for_navigation { page_command("Page.reload") }
+        end
+        alias reload refresh
+
+        private
+
+        def wait_for_page_load(url, retried: false)
+          deadline = await_navigation do
+            @client.command("Page.navigate", { url: url }, async: true, session_id: @session_id)
+          end
+          handle_navigation_crash(url, deadline, retried: retried)
+        end
+
+        # Lightpanda may kill the WebSocket or crash during complex page
+        # navigation (lightpanda-io/browser#1849, #1854). Reconnect and
+        # retry once. If the retry also crashes, raise a clear error
+        # instead of leaving the client in a dead state.
+        def handle_navigation_crash(url, deadline, retried:)
+          if @client.closed? && !retried
+            begin
+              reconnect
+              remaining = deadline - monotonic_time
+              if remaining.positive?
+                # Equivalent of re-entering go_to without leaking the retry
+                # bookkeeping into its public signature. enable_page_events is
+                # needed again: reconnect's clear_session_state reset the flag.
+                enable_page_events
+                wait_for_page_load(url, retried: true)
+              end
+            rescue DeadBrowserError
+              raise
+            rescue StandardError
+              # reconnect itself failed (process won't restart, port stuck, etc.).
+              # Fall through to the raise below — a second immediate reconnect
+              # attempt would just duplicate the failure we already swallowed.
+            end
+          end
+
+          return unless @client.closed?
+
+          raise DeadBrowserError, "Lightpanda crashed navigating to #{url}"
+        end
+
+        def safe_current_url
+          current_url
+        rescue StandardError
+          nil
+        end
+
+        # Wait for a navigation triggered by the given block.
+        # Uses the same loadEventFired + readyState fallback as go_to.
+        def wait_for_navigation(&)
+          enable_page_events
+          await_navigation(&)
+        end
+
+        # Step the session history by `offset` (-1 = back, +1 = forward) using
+        # native CDP. `Page.getNavigationHistory` returns the entry list and
+        # `currentIndex`; `Page.navigateToHistoryEntry` jumps to the chosen
+        # entry's `id`. No-op when the offset would step past either end so
+        # the behavior matches `history.back()` / `history.forward()` on a
+        # bounded session history.
+        def navigate_history(offset)
+          history = page_command("Page.getNavigationHistory")
+          target_index = history["currentIndex"] + offset
+          entries = history["entries"]
+          return if target_index.negative? || target_index >= entries.length
+
+          page_command("Page.navigateToHistoryEntry", entryId: entries[target_index]["id"])
+        end
+
+        # Common navigation lifecycle shared by `wait_for_page_load` (fresh
+        # `Page.navigate`) and `wait_for_navigation` (back / forward / reload).
+        # Subscribes to Page.loadEventFired, runs the trigger, waits briefly for
+        # the event, falls back to readyState polling for the remaining budget.
+        # The handler is unsubscribed via `ensure` so a raising trigger doesn't
+        # leak a subscription onto the next navigation. Returns the deadline so
+        # the caller can decide whether to attempt crash recovery.
+        def await_navigation
+          starting_url = safe_current_url
+          deadline = monotonic_time + @options.timeout
+          loaded = Utils::Event.new
+          handler = proc { loaded.set }
+          @client.on("Page.loadEventFired", &handler)
+
+          begin
+            yield
+
+            unless loaded.wait([2, @options.timeout].min)
+              remaining = deadline - monotonic_time
+              poll_ready_state(remaining, loaded_event: loaded, starting_url: starting_url) if remaining.positive?
+            end
+          ensure
+            @client.off("Page.loadEventFired", handler)
+          end
+
+          deadline
+        end
+
+        # Poll document.readyState as a fallback when Page.loadEventFired
+        # doesn't fire (CLAUDE.md rules call this out as load-bearing — do
+        # not remove). When starting_url is provided, the poll ignores
+        # readyState values from the old page (e.g. about:blank reports
+        # "complete" while the new page is still loading in the background).
+        def poll_ready_state(timeout, loaded_event: nil, starting_url: nil)
+          # Use a short per-evaluation timeout because Lightpanda may block
+          # all commands while navigating. Without this, a single evaluate()
+          # call would consume the entire @options.timeout, making the poll
+          # loop effectively a single attempt.
+          poll_cmd_timeout = [timeout / 5.0, 2].max
+
+          Utils::Wait.until(timeout: timeout, interval: 0.1) do
+            loaded_event&.set? || @client.closed? || page_ready?(poll_cmd_timeout, starting_url)
+          end
+        rescue TimeoutError
+          # Expected — readyState fallback exhausted its budget. The caller
+          # (await_navigation) keeps going and lets handle_navigation_crash
+          # decide whether the session is recoverable.
+        end
+
+        POLL_STATE_JS = "(function(){return{r:document.readyState,u:location.href}})()"
+        private_constant :POLL_STATE_JS
+
+        def page_ready?(cmd_timeout, starting_url)
+          response = @client.command(
+            "Runtime.evaluate",
+            { expression: POLL_STATE_JS, returnByValue: true, awaitPromise: true },
+            session_id: @session_id,
+            timeout: cmd_timeout
+          )
+          state = response.dig("result", "value")
+          return false unless state
+
+          url_changed = starting_url.nil? || state["u"] != starting_url
+          url_changed && %w[complete interactive].include?(state["r"])
+        rescue Error
+          false
+        end
+      end
+    end
+  end
+end