capybara-lightpanda 0.1.0 → 0.2.1

data/lib/capybara/lightpanda/browser.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "forwardable"
-require "uri"
 require "concurrent-ruby"
 
 module Capybara
@@ -9,7 +8,7 @@ module Capybara
     class Browser
       extend Forwardable
 
-      attr_reader :options, :process, :client, :target_id, :session_id, :frame_stack
+      attr_reader :options, :process, :client, :target_id, :session_id, :browser_context_id, :frame_stack
 
       delegate %i[on off] => :client
 
@@ -30,27 +29,19 @@ module Capybara
         @client = nil
         @target_id = nil
         @session_id = nil
+        @browser_context_id = nil
         @started = false
         @page_events_enabled = false
-        @modal_responses = []
         @modal_messages = []
         @modal_handler_installed = false
         @frame_stack = []
         @frames = Concurrent::Hash.new
         @turbo_event = Utils::Event.new
         @turbo_event.set
-        @visited_origins = Concurrent::Set.new
 
         start
       end
 
-      # Set of `scheme://host:port` strings the browser has navigated to during
-      # this session. Used by Cookies#clear to enumerate cookies across all
-      # domains: Lightpanda's `Network.getCookies` (no urls param) is scoped
-      # to the current page's origin, so without tracked origins we'd miss
-      # cookies set on previously-visited domains.
-      attr_reader :visited_origins
-
       def start
         return if @started
 
@@ -62,13 +53,25 @@ module Capybara
           @client = Client.new(@process.ws_url, @options)
         end
 
+        create_browser_context
         create_page
 
         @started = true
       end
 
+      # Per-session BrowserContext (Chrome's incognito-profile primitive).
+      # Cookies, storage, and targets created within the context are wiped
+      # when it's disposed — so `reset` is one CDP call instead of an
+      # explicit cookies.clear / storage.clear / close-target dance.
+      # Mirrors ferrum's Contexts model.
+      def create_browser_context
+        result = @client.command("Target.createBrowserContext")
+        @browser_context_id = result["browserContextId"]
+      end
+
       def create_page
-        result = @client.command("Target.createTarget", { url: "about:blank" })
+        result = @client.command("Target.createTarget",
+                                 { url: "about:blank", browserContextId: @browser_context_id }.compact)
         @target_id = result["targetId"]
 
         attach_result = @client.command("Target.attachToTarget", { targetId: @target_id, flatten: true })
@@ -88,6 +91,33 @@ module Capybara
         start
       end
 
+      # Wipe per-session state — cookies, storage, all targets — and start
+      # over with a fresh BrowserContext. Mirrors ferrum's Browser#reset:
+      # one CDP call (`Target.disposeBrowserContext`) does the work that
+      # would otherwise require explicit cookies.clear / storage.clear /
+      # close-target dance, and the browser auto-isolates state for the
+      # new context. Driver#reset! delegates here.
+      #
+      # Side benefit: avoids `Page.navigate("about:blank")` against a
+      # non-blank tab, which doesn't actually replace the document on
+      # current Lightpanda nightly (lightpanda-io/browser#2363). The
+      # context-disposal path sidesteps that bug entirely.
+      def reset
+        dispose_browser_context
+        @client.clear_subscriptions
+        @page_events_enabled = false
+        @modal_handler_installed = false
+        @modal_messages.clear
+        @frame_stack.clear
+        # Network#reset, not #clear: disposing the BrowserContext also
+        # destroyed the Network domain and its subscriptions, so we must
+        # flip @enabled back to false — otherwise the next #enable
+        # short-circuits and traffic tracking is silently dead.
+        @network&.reset
+        create_browser_context
+        create_page
+      end
+
       # Recover after a WebSocket disconnect or process crash during navigation.
       # Restarts the process if it died, then creates a fresh client and page.
       def reconnect
@@ -98,6 +128,9 @@ module Capybara
         raise DeadBrowserError, "Cannot reconnect: no WebSocket URL" unless ws_url
 
         @client = Client.new(ws_url, @options)
+        # Process may have died; the old browserContextId is gone with it.
+        @browser_context_id = nil
+        create_browser_context
         create_page
         @page_events_enabled = false
       end
@@ -116,6 +149,9 @@ module Capybara
         @client = nil
         @process = nil
         @started = false
+        @browser_context_id = nil
+        @target_id = nil
+        @session_id = nil
         @modal_handler_installed = false
         @frame_stack.clear
       end
@@ -150,8 +186,6 @@ module Capybara
         else
           page_command("Page.navigate", url: url)
         end
-
-        record_visited_origin(url)
       end
       alias goto go_to
 
@@ -172,13 +206,14 @@ module Capybara
       # Run the block; if it raises NoExecutionContextError (the navigation
       # race window — lightpanda-io/browser#2187), wait for the next default
       # context to be signaled by Runtime.executionContextCreated, then
-      # retry once. Replaces blind 100 ms sleep retries.
-      def with_default_context_wait(timeout: 1.0)
-        yield
-      rescue NoExecutionContextError
-        raise unless wait_for_default_context(timeout)
-
-        yield
+      # retry. Up to `attempts` total tries; defaults to 3, can be bumped
+      # for stubborn flakes. Each retry blocks up to `timeout` seconds for
+      # the executionContextCreated signal — no blind sleeps.
+      def with_default_context_wait(timeout: 1.0, attempts: 3)
+        Utils::Attempt.with_retry(errors: NoExecutionContextError, max: attempts, wait: 0) do
+          wait_for_default_context(timeout)
+          yield
+        end
       end
 
       def back
@@ -215,7 +250,10 @@ module Capybara
       def evaluate(expression, *args)
         if args.empty?
           response = page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: true)
-          raise JavaScriptError, response if response["exceptionDetails"]
+          if response["exceptionDetails"]
+            debug_js_failure("evaluate", expression, response)
+            raise JavaScriptError, response
+          end
 
           return unwrap_call_result(response["result"])
         end
@@ -236,6 +274,15 @@ module Capybara
         nil
       end
 
+      # When LIGHTPANDA_DEBUG=1 is set, log the JS expression and full CDP
+      # response for every JsException to STDERR. Invaluable for isolating
+      # which exact JS triggers an upstream Lightpanda bug.
+      def debug_js_failure(site, expression, response)
+        return unless ENV["LIGHTPANDA_DEBUG"]
+
+        warn "[lightpanda:#{site}] expression:\n#{expression}\n[lightpanda:#{site}] response:\n#{response.inspect}\n"
+      end
+
       # Evaluate async JS with a callback. The user's script receives
       # the callback as its last argument (`arguments[arguments.length - 1]`),
       # matching Capybara's evaluate_async_script contract.
@@ -260,7 +307,10 @@ module Capybara
       # Evaluate JS and return a RemoteObject reference (for DOM nodes, arrays).
       def evaluate_with_ref(expression)
         response = page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: true)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("evaluate_with_ref", expression, response)
+          raise JavaScriptError, response
+        end
 
         result = response["result"]
         return nil if result["type"] == "undefined"
@@ -280,7 +330,10 @@ module Capybara
         params[:arguments] = args.map { |a| serialize_argument(a) } unless args.empty?
 
         response = page_command("Runtime.callFunctionOn", **params)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("call_function_on", function_declaration, response)
+          raise JavaScriptError, response
+        end
 
         result = response["result"]
         return nil if result["type"] == "undefined"
@@ -296,7 +349,7 @@ module Capybara
       # Release a remote object reference to free V8 memory.
       def release_object(remote_object_id)
         page_command("Runtime.releaseObject", objectId: remote_object_id)
-      rescue BrowserError, NoExecutionContextError
+      rescue BrowserError
         # Object may already be released or context destroyed
       end
 
@@ -315,6 +368,8 @@ module Capybara
       def find_within(remote_object_id, method, selector)
         result = call_function_on(remote_object_id, FIND_WITHIN_JS, method, selector, return_by_value: false)
         extract_node_object_ids(result)
+      rescue JavaScriptError => e
+        raise_invalid_selector(e, method, selector)
       end
 
       # objectId of document.activeElement, or nil if none/document detached.
@@ -472,14 +527,14 @@ module Capybara
       end
 
       # -- Modal/Dialog Support --
-      # Lightpanda auto-dismisses dialogs in headless mode: alert→OK,
-      # confirm→false, prompt→null. Page.javascriptDialogOpening fires
-      # (since 2026-04-03), so we capture messages for find_modal, but
-      # Page.handleJavaScriptDialog always errors with "No dialog is showing"
-      # and we never call it (the dispatch thread cannot make synchronous
-      # CDP calls without deadlocking). @modal_responses is retained so
-      # accept_modal/dismiss_modal preserve their API contract; the
-      # accept/dismiss choice is informational only.
+      # 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
@@ -488,20 +543,21 @@ module Capybara
 
         on("Page.javascriptDialogOpening") do |params|
           @modal_messages << { type: params["type"], message: params["message"] }
-          @modal_responses.shift
         end
 
         @modal_handler_installed = true
       end
 
-      def accept_modal(type, text: nil)
+      def accept_modal(_type, text: nil)
         prepare_modals
-        @modal_responses << { accept: true, text: text, type: type.to_s }
+        params = { accept: true }
+        params[:promptText] = text if text
+        page_command("LP.handleJavaScriptDialog", **params)
       end
 
-      def dismiss_modal(type)
+      def dismiss_modal(_type)
         prepare_modals
-        @modal_responses << { accept: false, type: type.to_s }
+        page_command("LP.handleJavaScriptDialog", accept: false)
       end
 
       def find_modal(type, text: nil, wait: options.timeout)
@@ -525,7 +581,6 @@ module Capybara
       end
 
       def reset_modals
-        @modal_responses.clear
         @modal_messages.clear
       end
 
@@ -539,20 +594,32 @@ module Capybara
         raise Capybara::ModalNotFound, "Unable to find modal dialog#{" with #{text}" if text}"
       end
 
+      # 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:"
+
       # JS function for finding elements within a node.
-      # Works in any execution context (top frame or iframe).
-      FIND_WITHIN_JS = <<~JS
+      # Works in any execution context (top frame or iframe). Any throw from
+      # querySelectorAll means the selector is malformed (the spec only allows
+      # SYNTAX_ERR DOMException; Lightpanda's V8 currently throws a generic
+      # Error with messages like "InvalidClassSelector"). Re-throw with the
+      # marker prefix so Ruby converts to InvalidSelector regardless.
+      FIND_WITHIN_JS = <<~JS.freeze
         function(method, selector) {
           if (method === 'xpath') {
             if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, this);
             return [];
           }
-          try { return Array.from(this.querySelectorAll(selector)); } catch(e) { return []; }
+          try { return Array.from(this.querySelectorAll(selector)); }
+          catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
         }
       JS
+      private_constant :FIND_WITHIN_JS
 
       # JS function for finding elements in an iframe's contentDocument.
-      FIND_IN_FRAME_JS = <<~JS
+      FIND_IN_FRAME_JS = <<~JS.freeze
         function(method, selector) {
           var doc;
           try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
@@ -561,9 +628,11 @@ module Capybara
             if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, doc);
             return [];
           }
-          try { return Array.from(doc.querySelectorAll(selector)); } catch(e) { return []; }
+          try { return Array.from(doc.querySelectorAll(selector)); }
+          catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
         }
       JS
+      private_constant :FIND_IN_FRAME_JS
 
       def find_in_document(method, selector)
         with_default_context_wait do
@@ -574,12 +643,18 @@ module Capybara
           js = if method == "xpath"
                  "(typeof _lightpanda !== 'undefined') ? _lightpanda.xpathFind(#{selector_literal}, document) : []"
                else
-                 "(function() { try { return Array.from(document.querySelectorAll(#{selector_literal})); } " \
-                   "catch(e) { return []; } })()"
+                 <<~CSS_FIND
+                   (function() {
+                     try { return Array.from(document.querySelectorAll(#{selector_literal})); }
+                     catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + #{selector_literal}); }
+                   })()
+                 CSS_FIND
                end
           result = evaluate_with_ref(js)
           extract_node_object_ids(result)
         end
+      rescue JavaScriptError => e
+        raise_invalid_selector(e, method, selector)
       end
 
       def find_in_frame(method, selector)
@@ -587,6 +662,16 @@ module Capybara
         result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector,
                                   return_by_value: false)
         extract_node_object_ids(result)
+      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.
@@ -603,12 +688,13 @@ module Capybara
 
         release_object(result["objectId"])
         ids
-      rescue StandardError
+      rescue Error
         []
       end
 
       def register_auto_scripts
         page_command("Page.addScriptToEvaluateOnNewDocument", source: XPathPolyfill::JS)
+        page_command("Page.addScriptToEvaluateOnNewDocument", source: XPathPolyfill::POLYFILLS_JS)
       end
 
       def subscribe_to_console_logs
@@ -727,7 +813,10 @@ module Capybara
       end
 
       def handle_evaluate_response(response)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("handle_evaluate_response", "(unknown — already-issued call)", response)
+          raise JavaScriptError, response
+        end
 
         result = response["result"]
         return nil if result["type"] == "undefined"
@@ -749,7 +838,10 @@ module Capybara
           arguments: args.map { |a| serialize_argument(a) },
         }
         response = page_command("Runtime.callFunctionOn", **params)
-        raise JavaScriptError, response if response["exceptionDetails"]
+        if response["exceptionDetails"]
+          debug_js_failure("call_with_args", function_declaration, response)
+          raise JavaScriptError, response
+        end
 
         return_by_value ? handle_evaluate_response(response) : unwrap_call_result(response["result"])
       end
@@ -811,23 +903,9 @@ module Capybara
       end
 
       def wait_for_page_load(url, retried:)
-        starting_url = safe_current_url
-        deadline = monotonic_time + @options.timeout
-        loaded = Utils::Event.new
-
-        handler = proc { loaded.set }
-        @client.on("Page.loadEventFired", &handler)
-
-        @client.command("Page.navigate", { url: url }, async: true, session_id: @session_id)
-
-        # Give loadEventFired a brief window (fast path), then fall back
-        # to readyState polling with the remaining budget.
-        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?
+        deadline = await_navigation do
+          @client.command("Page.navigate", { url: url }, async: true, session_id: @session_id)
         end
-
-        @client.off("Page.loadEventFired", handler)
         handle_navigation_crash(url, deadline, retried: retried)
       end
 
@@ -864,6 +942,21 @@ module Capybara
         nil
       end
 
+      def dispose_browser_context
+        return unless @browser_context_id
+
+        begin
+          @client.command("Target.disposeBrowserContext", { browserContextId: @browser_context_id })
+        rescue StandardError
+          # Context may already be disposed or the WS may be down; we
+          # recreate either way.
+        ensure
+          @browser_context_id = nil
+          @target_id = nil
+          @session_id = nil
+        end
+      end
+
       def restart_process_if_dead
         return unless @process && !@process.alive?
 
@@ -883,23 +976,37 @@ module Capybara
 
       # Wait for a navigation triggered by the given block.
       # Uses the same loadEventFired + readyState fallback as go_to.
-      def wait_for_navigation
+      def wait_for_navigation(&)
         enable_page_events
+        await_navigation(&)
+      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)
 
-        yield
+        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?
+          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
 
-        @client.off("Page.loadEventFired", handler)
+        deadline
       end
 
       # Poll document.readyState as a fallback when Page.loadEventFired
@@ -938,26 +1045,13 @@ module Capybara
 
         url_changed = starting_url.nil? || state["u"] != starting_url
         url_changed && %w[complete interactive].include?(state["r"])
-      rescue StandardError
+      rescue Error
         false
       end
 
       def monotonic_time
         ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       end
-
-      # Capture `scheme://host:port` from a navigated URL so Cookies#clear can
-      # enumerate cookies across all visited domains. Skips opaque URLs
-      # (about:blank, data:, etc.) and any URI parser failure.
-      def record_visited_origin(url)
-        uri = URI.parse(url)
-        return unless uri.scheme && uri.host
-
-        port = uri.port || (uri.scheme == "https" ? 443 : 80)
-        @visited_origins << "#{uri.scheme}://#{uri.host}:#{port}"
-      rescue URI::InvalidURIError, NoMethodError
-        nil
-      end
     end
   end
 end

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

@@ -4,9 +4,18 @@ module Capybara
   module Lightpanda
     class Client
       class Subscriber
-        def initialize
+        # Default error sink: write a one-line warning so a misbehaving handler
+        # is visible without crashing the CDP message thread. Tests can inject
+        # a custom proc via `on_error:` to capture failures.
+        DEFAULT_ON_ERROR = lambda do |event, error|
+          warn("[capybara-lightpanda] subscriber callback for #{event.inspect} raised " \
+               "#{error.class}: #{error.message}")
+        end
+
+        def initialize(on_error: DEFAULT_ON_ERROR)
           @subscriptions = Hash.new { |h, k| h[k] = [] }
           @mutex = Mutex.new
+          @on_error = on_error
         end
 
         def subscribe(event, &block)
@@ -25,10 +34,28 @@ module Capybara
           end
         end
 
+        # Run every callback registered for `event`. Exceptions in one
+        # callback must not stop the others or propagate out — the message
+        # thread sets `abort_on_exception = true`, so an unhandled raise
+        # would tear down the entire CDP connection.
+        #
+        # Two layers of rescue:
+        #   1. The callback itself may raise — route to @on_error.
+        #   2. @on_error itself may raise (custom hook, broken stderr) —
+        #      swallow at the last level so the dispatch loop survives.
         def dispatch(event, params)
           callbacks = @mutex.synchronize { @subscriptions[event].dup }
 
-          callbacks.each { |callback| callback.call(params) }
+          callbacks.each do |callback|
+            callback.call(params)
+          rescue StandardError => e
+            begin
+              @on_error.call(event, e)
+            rescue StandardError
+              # The error sink failed — nothing to do but keep going. We
+              # cannot log here without re-entering the broken path.
+            end
+          end
         end
 
         def subscribed?(event)

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

@@ -133,7 +133,7 @@ module Capybara
         def read_handshake_response
           started_at = Time.now
 
-          while @status != :open && Time.now - started_at < @options.timeout
+          while @status != :open && Time.now - started_at < @options.handshake_timeout
             next unless @socket.wait_readable(0.1)
 
             begin
@@ -144,7 +144,9 @@ module Capybara
             end
           end
 
-          raise TimeoutError, "WebSocket connection timeout" unless @status == :open
+          return if @status == :open
+
+          raise TimeoutError, "WebSocket handshake timed out after #{@options.handshake_timeout}s"
         end
 
         def parse_message(data)

data/lib/capybara/lightpanda/client.rb

@@ -60,6 +60,13 @@ module Capybara
         @subscriber.unsubscribe(event, block)
       end
 
+      # Drop all event subscriptions without closing the WebSocket. Used by
+      # Browser#recreate_page so a fresh target's event handlers don't pile
+      # up on top of the previous target's subscriptions.
+      def clear_subscriptions
+        @subscriber.clear
+      end
+
       def close
         @ws&.close
         @message_thread&.join(1) || @message_thread&.kill