capybara-lightpanda 0.9.0 → 0.10.0

data/lib/capybara/lightpanda/browser.rb

@@ -7,6 +7,7 @@ require_relative "browser/finder"
 require_relative "browser/navigation"
 require_relative "browser/modals"
 require_relative "browser/console"
+require_relative "browser/selenium_compat"
 
 module Capybara
   module Lightpanda
@@ -18,6 +19,7 @@ module Capybara
       include Navigation
       include Modals
       include Console
+      include SeleniumCompat
 
       attr_reader :options, :process, :client, :target_id, :session_id, :browser_context_id, :frame_stack
 
@@ -78,10 +80,17 @@ module Capybara
         @process&.version
       end
 
+      # Set on the nightly/dev channel only; nil for a tagged release, which
+      # carries no build counter. `release` is its mirror image — exactly one of
+      # the two is non-nil once the process has started.
       def nightly_build
         @process&.nightly_build
       end
 
+      def release
+        @process&.release
+      end
+
       def initialize(options = {})
         @options = Options.new(options)
         @process = nil
@@ -94,8 +103,12 @@ module Capybara
         @modal_messages = []
         @modal_messages_mutex = Mutex.new
         @modal_handler_installed = false
+        @modal_armed = false
+        @unhandled_modal = nil
         @console_logs = []
         @console_logs_mutex = Mutex.new
+        @page_errors = []
+        @page_errors_mutex = Mutex.new
         @frame_stack = []
         @turbo_event = Utils::Event.new
         @turbo_event.set
@@ -149,7 +162,23 @@ module Capybara
         # clear_session_state's network.reset flipped @enabled back, so this
         # re-subscribes on the fresh context.
         network.enable
+        # Opt into file downloads when a destination exists (driver :save_path
+        # or Capybara.save_path). No-op otherwise. Must run after the context
+        # is loaded — Browser.setDownloadBehavior is a no-op without one.
+        downloads.enable(configured_download_path)
         register_auto_scripts
+        set_viewport
+        # Subscribe to dialogs from the first page, not lazily on the first
+        # accept_modal — otherwise a dialog nobody pre-armed is invisible and
+        # the unhandled-modal check below has nothing to report.
+        prepare_modals
+      end
+
+      # Download destination: explicit :save_path option wins, else
+      # Capybara.save_path (Cuprite parity). nil => downloads stay off.
+      def configured_download_path
+        @options.save_path ||
+          (defined?(Capybara) && Capybara.respond_to?(:save_path) ? Capybara.save_path : nil)
       end
 
       # Wipe per-session state — cookies, storage, all targets — and start
@@ -193,14 +222,23 @@ module Capybara
       def clear_session_state
         @page_events_enabled = false
         @modal_handler_installed = false
-        @modal_messages_mutex.synchronize { @modal_messages.clear }
+        @modal_messages_mutex.synchronize do
+          @modal_messages.clear
+          @modal_armed = false
+          @unhandled_modal = nil
+        end
         @console_logs_mutex.synchronize { @console_logs.clear }
+        @page_errors_mutex.synchronize { @page_errors.clear }
         clear_frames
         # 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
+        # Same contract for Downloads: the disposed context drops the
+        # download config + subscriptions, so reset re-arms create_page's
+        # downloads.enable on the fresh context.
+        @downloads&.reset
       end
 
       # Liveness of the CDP transport. Driver#browser checks this to decide
@@ -218,8 +256,12 @@ module Capybara
         # instance leaves @enabled true and create_page's network.enable
         # no-ops, silently killing status_code/traffic capture. Guarded on
         # @client: with no client the handlers are already moot and
-        # unsubscribe would have nothing to detach from.
-        @network&.reset if @client
+        # unsubscribe would have nothing to detach from. Downloads carries the
+        # same subscription contract, so it resets under the same guard.
+        if @client
+          @network&.reset
+          @downloads&.reset
+        end
         begin
           @client&.close
         rescue StandardError
@@ -325,7 +367,7 @@ module Capybara
       # objectId, replaces input.files with a real FileList, and fires
       # `input`/`change`. The submitted form then carries the bytes as
       # multipart/form-data (PR #2654, build ≥6672) — both halves are needed,
-      # which is why MINIMUM_NIGHTLY_BUILD sits at the 6672 floor. Paths are
+      # and both are guaranteed by the MINIMUM_NIGHTLY_BUILD floor. Paths are
       # read off the machine running Lightpanda (local for the spawned process).
       def set_file_input_files(remote_object_id, paths)
         page_command("DOM.setFileInputFiles", objectId: remote_object_id, files: paths)
@@ -391,6 +433,7 @@ module Capybara
 
         @default_context_event.wait(@options.timeout)
         @turbo_event.wait(@options.timeout)
+        check_unhandled_modal!
       end
 
       def keyboard
@@ -401,6 +444,10 @@ module Capybara
         @network ||= Network.new(self)
       end
 
+      def downloads
+        @downloads ||= Downloads.new(self)
+      end
+
       def cookies
         @cookies ||= Cookies.new(self)
       end
@@ -455,6 +502,53 @@ module Capybara
         page_command("Page.addScriptToEvaluateOnNewDocument", source: AutoScripts::JS)
       end
 
+      # Apply the `window_size` option as a JS-visible viewport: it drives
+      # window.innerWidth/innerHeight and the viewport `matchMedia` / `@media`
+      # evaluate against, so responsive branches resolve at the requested size.
+      # It is NOT layout — Lightpanda has no rendering engine, so nothing
+      # reflows and getBoundingClientRect stays synthetic.
+      #
+      # Re-applied on every create_page rather than once at connect. The
+      # override lives on the CDP-connection-scoped Browser upstream, so it
+      # already survives Driver#reset!'s disposeBrowserContext; re-sending is
+      # one idempotent call that also covers the reconnect path, where the
+      # connection (and therefore the override) is genuinely new.
+      #
+      # window_size is validated in Options#initialize, which runs before the
+      # process is spawned — a bad value must not leave an orphaned browser
+      # behind, and raising from here would (Browser#initialize starts the
+      # process before create_page ever runs).
+      #
+      # Public (declared below the private section via `public :set_viewport`)
+      # because Driver#resize_window_to drives it mid-test: with no arguments
+      # it re-applies the configured size, which is what create_page wants.
+      # SHARP EDGE, verified 2026-07-25 on nightly 8285: this updates
+      # window.innerWidth/innerHeight and what `matchMedia` reports
+      # immediately, but it does NOT re-resolve `@media` rules for the document
+      # already loaded. Lightpanda fixes the cascade when a document is parsed
+      # and nothing invalidates it on a metrics change, so a page loaded at
+      # 1920 keeps rendering its desktop branch even while `matchMedia`
+      # ("(max-width: 500px)") reports true. Navigating (Driver#visit) parses
+      # under the new metrics and resolves correctly.
+      #
+      # No workaround shipped on purpose. DOM/CSSOM mutations look like they
+      # force a re-cascade but don't survive scrutiny (the probe that suggested
+      # otherwise had been contaminated by the previous iteration's viewport),
+      # so anything here would be a guess dressed up as a fix. Driver's window
+      # methods document the resize-then-visit shape instead.
+      def set_viewport(width = nil, height = nil)
+        width, height = @options.window_size if width.nil? || height.nil?
+        page_command("Emulation.setDeviceMetricsOverride", width: width, height: height)
+        [width, height]
+      end
+
+      # The viewport as the page currently sees it. Read back from JS rather
+      # than echoing what we last set, so it stays truthful if a page (or a
+      # direct Emulation call through #execute_cdp) moved it behind our back.
+      def viewport_size
+        evaluate("[window.innerWidth, window.innerHeight]")
+      end
+
       # Track default-execution-context availability via Runtime events.
       # Lightpanda destroys the V8 default context at navigation start (long
       # before frameNavigated fires), then re-creates it once the new page
@@ -510,6 +604,12 @@ module Capybara
       def monotonic_time
         ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       end
+
+      # Viewport control is API, not lifecycle: Driver#resize_window_to and
+      # #window_size call it mid-test. It lives up in the private section
+      # beside register_auto_scripts because create_page is its other caller
+      # and the two read together.
+      public :set_viewport, :viewport_size
     end
   end
 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

@@ -117,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)
@@ -158,6 +174,83 @@ module Capybara
         end
       end
 
+      # -- 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
+
+      # 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
+
+      alias fullscreen_window maximize_window
+
+      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
@@ -196,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
@@ -273,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.

data/lib/capybara/lightpanda/errors.rb

@@ -13,6 +13,11 @@ module Capybara
     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

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

@@ -0,0 +1,74 @@
+// --- Uncaught page errors ---
+// Lightpanda implements no `Runtime.exceptionThrown` (upstream gap, wishlist
+// B19), so an uncaught exception in page JS reaches no CDP client at all. It is
+// invisible to console_logs, which only ever sees explicit console.* calls, so
+// a handler that dies on a TypeError leaves no trace and the failure surfaces
+// far away as ElementNotFound on whatever it was supposed to produce. That is
+// the exact shape of the solidus taxon-tree failure in real-apps causes.yml.
+//
+// These listeners are passive — no preventDefault, so nothing the page would
+// otherwise see is swallowed, and nothing that would have propagated stops
+// propagating. They re-emit through the same console.debug sentinel channel
+// turbo.js uses, and console.rb routes them into Browser#page_errors rather
+// than #console_logs. Keeping the two apart is deliberate: console_logs stays
+// "the console.* calls the page made", which is what Chrome models (an
+// exception is exceptionThrown, not consoleAPICalled) and what Playwright and
+// Puppeteer expose (pageerror, separate from console). Folding exceptions into
+// console_logs would also break every suite already asserting that buffer is
+// free of errors.
+//
+// Delete this file once upstream emits Runtime.exceptionThrown and the floor
+// covers it: subscribe Browser::Console to that event and feed the same buffer.
+function _reportPageError(fields) {
+  try {
+    console.debug('__lightpanda_page_error_' + JSON.stringify(fields));
+  } catch (e) {
+    // A field that won't serialize (a getter that throws, a cyclic `reason`)
+    // must not turn one page error into two, so report the kind and move on.
+    try {
+      console.debug('__lightpanda_page_error_' + JSON.stringify({
+        kind: fields && fields.kind ? fields.kind : 'error',
+        message: '(page error could not be serialized)'
+      }));
+    } catch (e2) {}
+  }
+}
+
+window.addEventListener('error', function (e) {
+  // A failed <img>/<script>/<link> fetch fires `error` too, but on the element
+  // and without bubbling, so it shouldn't reach this listener. Guard anyway
+  // (Lightpanda's dispatch need not match Chrome's exactly) and identify those
+  // by their missing string `message` — a resource failure is a network fact
+  // and Network#traffic already carries it.
+  if (!e || typeof e.message !== 'string') return;
+
+  _reportPageError({
+    kind: 'error',
+    message: e.message,
+    url: typeof e.filename === 'string' ? e.filename : '',
+    line: typeof e.lineno === 'number' ? e.lineno : null,
+    column: typeof e.colno === 'number' ? e.colno : null,
+    // Cap the stack: it rides a console argument over the CDP WebSocket, and a
+    // deep recursion stack can be megabytes.
+    stack: e.error && typeof e.error.stack === 'string' ? e.error.stack.slice(0, 4000) : null
+  });
+});
+
+window.addEventListener('unhandledrejection', function (e) {
+  var reason = e ? e.reason : null;
+  var message;
+  try {
+    message = reason && reason.message ? String(reason.message) : String(reason);
+  } catch (err) {
+    message = '(rejection reason could not be stringified)';
+  }
+
+  _reportPageError({
+    kind: 'unhandledrejection',
+    message: message,
+    url: '',
+    line: null,
+    column: null,
+    stack: reason && typeof reason.stack === 'string' ? reason.stack.slice(0, 4000) : null
+  });
+});