capybara-lightpanda 0.8.0 → 0.10.0

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

@@ -58,6 +58,8 @@ module Capybara
           end
         end
 
+        # Test seam: no production caller, but subscriber_test asserts
+        # unsubscribe/clear semantics through it.
         def subscribed?(event)
           @mutex.synchronize { @subscriptions.key?(event) && @subscriptions[event].any? }
         end

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

@@ -4,6 +4,8 @@ require "json"
 require "socket"
 require "websocket/driver"
 
+require_relative "../utils/attempt"
+
 module Capybara
   module Lightpanda
     class Client
@@ -36,7 +38,7 @@ module Capybara
 
           @status = :closing
           @messages.close
-          @driver&.close
+          @driver_mutex.synchronize { @driver&.close }
           @thread&.join(1) || @thread&.kill
           @socket&.close
           @status = :closed
@@ -46,15 +48,10 @@ module Capybara
           @status == :closed || @status == :error
         end
 
-        def open?
-          @status == :open
-        end
-
         def write(data)
           @socket.write(data)
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
-          @status = :closed
-          @messages.close
+          mark_dead
         end
 
         private
@@ -73,13 +70,9 @@ module Capybara
           start_reader_thread
         end
 
-        def connect_with_retry(host, port, retries: 10, delay: 0.1)
-          retries.times do |i|
-            return TCPSocket.new(host, port)
-          rescue Errno::ECONNREFUSED
-            raise if i == retries - 1
-
-            sleep delay
+        def connect_with_retry(host, port)
+          Utils::Attempt.with_retry(errors: Errno::ECONNREFUSED, max: 10, wait: 0.1) do
+            TCPSocket.new(host, port)
           end
         end
 
@@ -97,8 +90,7 @@ module Capybara
           end
 
           @driver.on(:close) do
-            @status = :closed
-            @messages.close
+            mark_dead
           end
 
           @driver.on(:error) do |event|
@@ -109,8 +101,7 @@ module Capybara
             # process. Mark the connection dead and let Client#command
             # surface DeadBrowserError on its next dispatch via closed?.
             @logger&.puts("✗ WebSocket error: #{event.message}")
-            @status = :error
-            @messages.close
+            mark_dead(:error)
           end
         end
 
@@ -127,8 +118,7 @@ module Capybara
                 data = @socket.readpartial(4096)
                 @driver_mutex.synchronize { @driver.parse(data) }
               rescue Errno::ECONNRESET, Errno::EPIPE, IOError
-                @status = :closed
-                @messages.close
+                mark_dead
                 break
               end
             end
@@ -144,7 +134,7 @@ module Capybara
             begin
               data = @socket.readpartial(4096)
               @driver.parse(data)
-            rescue EOFError
+            rescue Errno::ECONNRESET, Errno::EPIPE, IOError # IOError covers EOFError
               raise DeadBrowserError, "Connection closed during handshake"
             end
           end
@@ -154,6 +144,14 @@ module Capybara
           raise TimeoutError, "WebSocket handshake timed out after #{@options.handshake_timeout}s"
         end
 
+        # Single home for the "dead implies queue closed" invariant: every
+        # path that gives up on the connection must close @messages so the
+        # Client message thread's blocking pop returns.
+        def mark_dead(status = :closed)
+          @status = status
+          @messages.close
+        end
+
         def parse_message(data)
           JSON.parse(data, max_nesting: false)
         rescue JSON::ParserError => e

data/lib/capybara/lightpanda/client.rb

@@ -9,10 +9,7 @@ require_relative "client/subscriber"
 module Capybara
   module Lightpanda
     class Client
-      attr_reader :ws_url, :options
-
       def initialize(ws_url, options)
-        @ws_url = ws_url
         @options = options
         @ws = WebSocket.new(ws_url, options)
         @command_id = 0
@@ -118,7 +115,11 @@ module Capybara
       def handle_message(message)
         if message["id"]
           pending = @pendings[message["id"]]
-          pending&.set(message)
+          # try_set, not set: a duplicate frame for an already-answered id
+          # (Lightpanda emits occasional malformed/duplicate frames — see
+          # upstream-wishlist.md A41) would raise MultipleAssignmentError on
+          # this thread, and abort_on_exception would kill the whole process.
+          pending&.try_set(message)
         elsif message["method"]
           @subscriber.dispatch(message["method"], message["params"])
         end

data/lib/capybara/lightpanda/downloads.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Capybara
+  module Lightpanda
+    # File-download tracker built on `Browser.setDownloadBehavior` (upstream PR
+    # #2722, build >= 7545, guaranteed by MINIMUM_NIGHTLY_BUILD). When a
+    # navigation response carries `Content-Disposition: attachment`, Lightpanda
+    # streams the body to disk under `downloadPath` and — with
+    # `eventsEnabled: true` — emits `Browser.downloadWillBegin` /
+    # `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.
+    #
+    # Structure deliberately mirrors Network (same browser ref, same mutex +
+    # subscribe/unsubscribe lifecycle, same reset-after-disposeBrowserContext
+    # contract) so the two trackers behave identically under create_page/reset.
+    class Downloads
+      attr_reader :browser, :path
+
+      # How long #wait gives a download to BEGIN (the downloadWillBegin frame
+      # can arrive a beat after the click that triggers it, once the click's
+      # own wait_for_idle has already returned). Once a download has begun we
+      # wait the full `timeout` for it to finish.
+      DOWNLOAD_BEGIN_GRACE = 1.0
+
+      def initialize(browser)
+        @browser = browser
+        @path = nil
+        @enabled = false
+        @mutex = Mutex.new
+        @pending = {}  # guid => on-disk basename (from suggestedFilename)
+        @files = []    # absolute paths of completed downloads, in order
+        @started = 0   # monotonic count of downloads begun this session
+        @will_handler = nil
+        @progress_handler = nil
+      end
+
+      # Opt into downloads, writing completed files under `save_path`. No-op
+      # when `save_path` is blank — downloads then stay at Lightpanda's `deny`
+      # default. Connection-scoped (browser.command) like Network.enable;
+      # Browser#create_page calls this after the context is loaded (the CDP
+      # method is a no-op without one). Subscribe BEFORE the wire toggle so no
+      # event can slip past, and roll the handlers back if the command fails.
+      def enable(save_path)
+        return if @enabled || save_path.to_s.empty?
+
+        @path = File.expand_path(save_path.to_s)
+        FileUtils.mkdir_p(@path)
+        subscribe
+        begin
+          browser.command("Browser.setDownloadBehavior",
+                          behavior: "allow", downloadPath: @path, eventsEnabled: true)
+        rescue StandardError
+          unsubscribe
+          @path = nil
+          raise
+        end
+        @enabled = true
+      end
+
+      # Absolute paths of downloads completed this session (newest last).
+      def files
+        @mutex.synchronize { @files.dup }
+      end
+
+      # Monotonic count of downloads that have begun this session. Used by
+      # #wait to detect "a download started since I was called" even after the
+      # event queue has drained and @pending is empty again.
+      def started_count
+        @mutex.synchronize { @started }
+      end
+
+      def in_progress?
+        @mutex.synchronize { @pending.any? }
+      end
+
+      # Block until in-flight downloads finish, then return the completed-file
+      # list. Non-raising, matching Network#wait_for_idle.
+      #
+      # The triggering click returns (its wait_for_idle settles on the
+      # navigation's network response) slightly BEFORE the downloadWillBegin
+      # frame is processed, so a naive `wait until !in_progress?` would see an
+      # empty queue and return before the download even registered. Instead:
+      # give a download up to DOWNLOAD_BEGIN_GRACE to begin (tracked by the
+      # monotonic @started counter, immune to the queue already having drained),
+      # then wait up to `timeout` for every in-flight download to finish.
+      def wait(timeout: 5)
+        baseline = started_count
+        clock = -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+        hard_deadline = clock.call + timeout
+        begin_deadline = clock.call + [timeout, DOWNLOAD_BEGIN_GRACE].min
+
+        loop do
+          began = started_count > baseline
+          done = (began ? !in_progress? : clock.call >= begin_deadline) || clock.call >= hard_deadline
+          return files if done
+
+          sleep 0.02
+        end
+      end
+
+      def clear
+        @mutex.synchronize do
+          @files.clear
+          @pending.clear
+          @started = 0
+        end
+      end
+
+      # Wipe local state after Target.disposeBrowserContext, which drops both
+      # the subscriptions and the per-connection download config — leaving
+      # @enabled true would no-op the next #enable. Mirrors Network#reset.
+      def reset
+        unsubscribe
+        clear
+        @enabled = false
+        @path = nil
+      end
+
+      private
+
+      def subscribe
+        @will_handler = build_will_handler
+        @progress_handler = build_progress_handler
+        browser.on("Browser.downloadWillBegin", &@will_handler)
+        browser.on("Browser.downloadProgress", &@progress_handler)
+      end
+
+      # downloadWillBegin carries {guid, url, suggestedFilename}. behavior
+      # "allow" writes the file under the (path-stripped) suggested name, so
+      # remember guid => basename to resolve the absolute path on completion.
+      def build_will_handler
+        lambda do |params|
+          guid = params["guid"]
+          name = File.basename(params["suggestedFilename"].to_s)
+          next if guid.nil? || name.empty?
+
+          @mutex.synchronize do
+            @pending[guid] = name
+            @started += 1
+          end
+        end
+      end
+
+      # downloadProgress carries {guid, state}. On "completed" the file is on
+      # disk at downloadPath/basename; "canceled" just drops the pending entry.
+      def build_progress_handler
+        lambda do |params|
+          guid = params["guid"]
+          case params["state"]
+          when "completed"
+            @mutex.synchronize do
+              name = @pending.delete(guid)
+              @files << File.join(@path, name) if name && @path
+            end
+          when "canceled"
+            @mutex.synchronize { @pending.delete(guid) }
+          end
+        end
+      end
+
+      def unsubscribe
+        browser.off("Browser.downloadWillBegin", @will_handler) if @will_handler
+        browser.off("Browser.downloadProgress", @progress_handler) if @progress_handler
+        @will_handler = nil
+        @progress_handler = nil
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/driver.rb

@@ -10,7 +10,7 @@ module Capybara
 
       attr_reader :app, :options
 
-      delegate %i[current_url title status_code response_headers] => :browser
+      delegate %i[current_url title status_code response_headers frame_url frame_title] => :browser
 
       def initialize(app, options = {})
         super()
@@ -26,9 +26,7 @@ module Capybara
       end
 
       def browser_alive?
-        @browser.client && !@browser.client.closed?
-      rescue StandardError
-        false
+        !@browser.nil? && @browser.alive?
       end
 
       # Escape hatch to the underlying Browser for callers that need raw CDP
@@ -119,6 +117,22 @@ module Capybara
         network.wait_for_idle(timeout: timeout, connections: connections)
       end
 
+      # -- Downloads --
+      # 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.
+
+      def downloads
+        browser.downloads.files
+      end
+
+      # Block until in-flight downloads finish (or timeout); returns the file
+      # list. Click the download trigger first, then call this.
+      def wait_for_download(timeout: 5)
+        browser.downloads.wait(timeout: timeout)
+      end
+
       # -- Cookie Management --
 
       def set_cookie(name, value, **options)
@@ -160,42 +174,97 @@ module Capybara
         end
       end
 
-      # Capybara::Driver::Base falls back to running these via the top
-      # execution context, which always reports the parent document. Resolve
-      # them through the iframe element's contentWindow / contentDocument so
-      # they reflect the active frame.
-      def frame_url
-        frame = browser.frame_stack.last
-        return browser.current_url unless frame
+      # -- Window Support --
+      # Single-window driver. Lightpanda's BrowserContext is 1:1:1 with
+      # Session/Page/target and rejects a second Target.createTarget with
+      # TargetAlreadyLoaded (upstream #1962, maintainer-owned), so there is
+      # exactly one window and its handle is the CDP target id.
+      #
+      # Resizing drives Emulation.setDeviceMetricsOverride, so it is real for
+      # window.innerWidth/innerHeight and for what `matchMedia` reports. Two
+      # limits worth knowing before writing a responsive spec:
+      #
+      #   1. It is not layout. Element geometry stays synthetic, so a resize
+      #      changes which CSS branch applies, never where anything sits.
+      #   2. `@media` rules do NOT re-resolve for the document already on
+      #      screen — Lightpanda fixes the cascade at parse time and a metrics
+      #      change doesn't invalidate it. So resize, THEN visit:
+      #
+      #        page.current_window.resize_to(375, 667)
+      #        visit "/pricing"   # parses under the new metrics
+      #        assert_selector "#mobile-cta"
+      #
+      #      Resizing without re-visiting leaves `matchMedia` and the rendered
+      #      branch disagreeing. See Browser#set_viewport for the verification.
+
+      def current_window_handle
+        browser.target_id
+      end
+
+      def window_handles
+        [browser.target_id]
+      end
+
+      def switch_to_window(handle)
+        return if handle == browser.target_id
+
+        raise NoSuchPageError, "Window #{handle.inspect} does not exist. " \
+                               "Lightpanda supports a single window per session."
+      end
+
+      # Capybara's Window#current? rescues this to decide whether a handle is
+      # still live, so it must be a class, not a raise.
+      def no_such_window_error
+        NoSuchPageError
+      end
+
+      def window_size(handle)
+        assert_current_window!(handle)
+        browser.viewport_size
+      end
+
+      def resize_window_to(handle, width, height)
+        assert_current_window!(handle)
+        browser.set_viewport(width, height)
+      end
 
-        browser.call_function_on(frame.remote_object_id,
-                                 "function() { return this.contentWindow.location.href }")
+      # No window manager and no layout, so "as large as the screen" has no
+      # meaning beyond the configured size. Both reset to it rather than
+      # raising, because suites call maximize defensively in setup and a
+      # raise there would take out the example before it starts.
+      def maximize_window(handle)
+        assert_current_window!(handle)
+        browser.set_viewport
       end
 
-      def frame_title
-        frame = browser.frame_stack.last
-        return browser.title unless frame
+      alias fullscreen_window maximize_window
 
-        browser.call_function_on(frame.remote_object_id,
-                                 "function() { return this.contentDocument.title }")
+      def open_new_window(_kind = :tab)
+        raise Capybara::NotSupportedByDriverError,
+              "Lightpanda serves a single target per CDP connection (upstream lightpanda-io/browser#1962), " \
+              "so a second window cannot be opened. Drive the second page in its own Capybara session instead."
+      end
+
+      def close_window(_handle)
+        raise Capybara::NotSupportedByDriverError,
+              "Lightpanda has a single window per session; closing it would end the session. " \
+              "Use Driver#reset! to start a fresh one."
       end
 
       # -- Modal/Dialog Support --
 
+      # find_modal owns the wait default (browser.options.timeout) — pass
+      # wait only when the caller overrode it.
       def accept_modal(type, **options, &block)
         browser.accept_modal(type, text: options[:with])
         block&.call
-        browser.find_modal(type,
-                           text: options[:text],
-                           wait: options.fetch(:wait, browser.options.timeout))
+        browser.find_modal(type, **{ text: options[:text], wait: options[:wait] }.compact)
       end
 
       def dismiss_modal(type, **options, &block)
         browser.dismiss_modal(type)
         block&.call
-        browser.find_modal(type,
-                           text: options[:text],
-                           wait: options.fetch(:wait, browser.options.timeout))
+        browser.find_modal(type, **{ text: options[:text], wait: options[:wait] }.compact)
       end
 
       # -- Screenshots --
@@ -220,8 +289,11 @@ module Capybara
       alias render save_screenshot
 
       # -- Headers (Cuprite-compatible driver surface) --
-      # Delegates to Network, which lazily enables the Network domain and
-      # remembers the headers across reset. Cuprite exposes these on the
+      # 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 = ...).
 
       def headers
@@ -241,12 +313,20 @@ module Capybara
       # Thin Cuprite-style 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
+      # turns programmer errors (e.g. a NoMethodError in browser.rb) into a
+      # silent quit-and-respawn on every example with zero signal. The warn
+      # keeps repeated respawns visible.
       def reset!
         browser.reset
-        @started = false
-      rescue StandardError
+      rescue Error, SystemCallError, IOError => e
+        warn "[capybara-lightpanda] reset! failed (#{e.class}: #{e.message}); respawning browser"
         @browser&.quit
         @browser = nil
+      ensure
+        @started = false
       end
 
       def quit
@@ -289,6 +369,17 @@ module Capybara
 
       private
 
+      # Every window method takes a handle because Capybara's Window objects
+      # carry one; with a single window the only valid value is the current
+      # target id. Reject anything else rather than silently operating on the
+      # wrong window.
+      def assert_current_window!(handle)
+        return if handle.nil? || handle == browser.target_id
+
+        raise NoSuchPageError, "Window #{handle.inspect} does not exist. " \
+                               "Lightpanda supports a single window per session."
+      end
+
       # 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.
@@ -315,14 +406,15 @@ module Capybara
       end
 
       # Walk through evaluate-script results turning DOM-node markers (the
-      # `{ "__lightpanda_node__" => "..." }` hashes produced by `Browser#unwrap_call_result`)
-      # into Lightpanda::Node instances so Capybara can wrap them as elements.
+      # `{ Browser::NODE_MARKER => "..." }` hashes produced by
+      # `Browser#unwrap_call_result`) into Lightpanda::Node instances so
+      # Capybara can wrap them as elements.
       def unwrap_script_result(value)
         case value
         when Array then value.map { |v| unwrap_script_result(v) }
         when Hash
-          if value.size == 1 && value.key?("__lightpanda_node__")
-            Node.new(self, value["__lightpanda_node__"])
+          if value.size == 1 && value.key?(Browser::NODE_MARKER)
+            Node.new(self, value[Browser::NODE_MARKER])
           else
             value.transform_values { |v| unwrap_script_result(v) }
           end

data/lib/capybara/lightpanda/errors.rb

@@ -5,11 +5,19 @@ module Capybara
     class Error < StandardError; end
 
     class ProcessTimeoutError < Error; end
+    # Subclass so external `rescue ProcessTimeoutError` keeps catching it;
+    # Process#start dispatches on the class instead of message matching.
+    class PortInUseError < ProcessTimeoutError; end
     class BinaryNotFoundError < Error; end
     class BinaryError < Error; end
     class UnsupportedPlatformError < Error; end
 
     class TimeoutError < Error; end
+    # A JS dialog opened with no accept_modal/dismiss_modal pre-arm in flight
+    # and the driver was configured with `raise_on_unhandled_modal: true`.
+    # Lightpanda has already applied its silent default by the time this is
+    # raised (confirm → cancel, prompt → null, alert → dismissed).
+    class UnhandledModalError < Error; end
 
     # Base class for any error originating from a CDP response or live browser
     # state. Lets callers `rescue BrowserError` to catch the whole CDP family
@@ -88,6 +96,22 @@ module Capybara
       end
     end
 
+    class InvalidSelector < Error
+      attr_reader :method, :selector
+
+      def initialize(message, method = nil, selector = nil)
+        @method = method
+        @selector = selector
+        super(message)
+      end
+    end
+
+    # --- Cuprite/Ferrum 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
+    # don't NameError on rescue lists that reference them.
     class MouseEventFailed < BrowserError
       attr_reader :node, :selector, :position
 
@@ -103,16 +127,6 @@ module Capybara
       end
     end
 
-    class InvalidSelector < Error
-      attr_reader :method, :selector
-
-      def initialize(message, method = nil, selector = nil)
-        @method = method
-        @selector = selector
-        super(message)
-      end
-    end
-
     class NoSuchPageError < Error; end
     class StatusError < Error; end
   end

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

@@ -0,0 +1,16 @@
+// --- Public surface ---
+// The one place that names window._lightpanda. References the function/var
+// declarations from turbo.js and predicates.js (hoisted into the same IIFE
+// scope by AutoScripts). Runs last in the concatenation order.
+window._lightpanda = {
+  turbo: {
+    pending: function() { return _pendingTurboOps; },
+    idle: function() { return _pendingTurboOps <= 0; }
+  },
+
+  isVisible: isVisible,
+  isObscured: isObscured,
+  isDisabled: isDisabled,
+  isContentEditable: isContentEditable,
+  visibleText: visibleText
+};

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

@@ -0,0 +1,15 @@
+// _lightpanda auto-injected bundle. Assembled by AutoScripts (auto_scripts.rb)
+// from the sibling source files in this directory and registered once per
+// session via Page.addScriptToEvaluateOnNewDocument, so it runs in every
+// document — top frame and every iframe.
+//
+// Each source file is a plain sequence of declarations/statements: no IIFE,
+// no `export`/`import`/`require`. AutoScripts wraps them in the IIFE and the
+// `window._lightpanda` idempotency guard. Keeping the files free of module
+// syntax means they parse identically as a classic browser script and as a
+// `new Function(...)` body — which is exactly how the Bun harness (test/js/)
+// loads predicates.js to test them without a build step.
+//
+// Concatenation order (set in auto_scripts.rb): banner, turbo, predicates,
+// attach. `attach.js` reads the names defined by `turbo.js`/`predicates.js`,
+// so it must come last.