capybara-lightpanda 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1c82db6d6a5d5662098021d24688d5ff16592b1cb6de95c2c422307487d91d0
-  data.tar.gz: 0f21620cae5dc33e640712565a64071a47d78e906520770bef8e2aa593b230ca
+  metadata.gz: f039526ec34b172b3824416cd6b7679720cabcb75455a1c3c46bbf0cc11b5d7b
+  data.tar.gz: '087e752b5baa7d09d43541e90654732e042f28535d53248fab9ab2769f656c01'
 SHA512:
-  metadata.gz: 27f0ce27958fdbb057b68b684429222cae534d0b32f06521608862a6407a5ceb89935cbfeb4ebfee7de70d7d7d78a92a6a36d547ffdae27171bef1a731606728
-  data.tar.gz: 492a709cf1117444126ac9429586dc861af46e8e52d779106478e7d96d4c3aff13c1756f9c6ece4d96f41610e4f79f3b7861d02d11eaf294cbc22594c5d28001
+  metadata.gz: b2430399381dbcb55f54eafbbb9fb81cc3c4ac5956e4bbc16d5dfe70fb1f347f7f8dfdf60044134c87ae739200911d22e986ce9b4d0a37a2f21ebf74887e50f1
+  data.tar.gz: 500584b0da1e6bd82737e213fdd13e10395334e0c971923e2f7fdcb78758251f36f50361272b66c1838a781bf134b724c7b1cc77761dfb28a9b6cfbd8de65d31

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.8.0] - 2026-06-12
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6736 (published 2026-06-12). The driver refuses to start against older binaries.
+
+### Added
+
+- `lightpanda:binary:*` rake tasks now load automatically inside Rails apps (via a Railtie), and the "Lightpanda is too old" error suggests a require-the-gem one-liner instead of those rake tasks. The old hint was a dead end: the tasks weren't loaded in Rails apps at all, and even with the Railtie they only exist under `RAILS_ENV=test` when the gem sits in the `:test` Gemfile group. (Found beta-testing a private Rails suite.)
+- `Driver#render` as an alias of `save_screenshot`. capybara-screenshot calls `driver.render(path)` for drivers it doesn't know, so every failing test in a capybara-screenshot suite logged "Screenshot could not be saved: undefined method 'render'" — once per failure.
+- `Driver#headers=` / `#add_headers` / `#headers`, delegating to the existing `Network` support. Cuprite exposes header writers on the driver and real suites call them there (`page.driver.headers = …`).
+- `Cookies#[]` as an alias of `#get` — the Ferrum/Cuprite spelling (`browser.cookies["session_id"]`).
+- `Browser#console_logs` / `#clear_console_logs` — console messages captured since the last session reset, as `{type:, text:, timestamp:, args:}` hashes (driver-internal Turbo sentinels excluded, buffer capped at 1,000 entries). Suites that assert "no JS errors leaked" no longer need to wire a custom Ferrum-style logger: `page.driver.browser.console_logs.select { |m| m[:type] == "error" }`. Note that Lightpanda currently reports both `console.log` and `console.warn` as type `"info"` — filter on `text` when you need to distinguish them.
+
+### Changed
+
+- Modal assertions match dialogs by message text regardless of the alert/confirm/prompt type, like Selenium and Cuprite — `accept_alert` around a `data-confirm` delete button now works.
+- Clicks dispatch the full pointer sequence (mousedown → mouseup → click). Widgets that open on mousedown — select2 v3 dropdowns, for example — now react to `click` / `select_from`.
+- The driver no longer re-dispatches `readystatechange` itself. Lightpanda fires the event natively as of nightly 6736 (lightpanda-io/browser#2708), so the shim added in 0.7.0 became redundant and was removed. Behavior is unchanged for Turbo/Hotwire apps — `turbo:load` still fires on every visit, now from the browser's own event.
+
+### Fixed
+
+- A failed binary download that falls back to a stale cached binary now warns loudly on stderr (with the original error and a re-provision one-liner) instead of logging only under `LIGHTPANDA_DEBUG`. VCR-guarded suites hit this path silently — VCR's blocking error is a `StandardError`, unlike raw WebMock's — and the only visible symptom was a confusing "Lightpanda is too old" error much later.
+- Turbo Streams over ActionCable now connect. Page-initiated WebSocket upgrades carry the document's `Origin` header as of nightly 6736 (lightpanda-io/browser#2710, guaranteed by the new minimum build), so ActionCable's request-forgery protection accepts the connection instead of rejecting it with `Request origin not allowed: nil`. `turbo-cable-stream-source` elements reach `[connected]` and `turbo_stream_for` broadcasts (solid_cable or any adapter) arrive in specs. If you had added `config.action_cable.disable_request_forgery_protection = true` to your test environment to work around this, you can remove it.
+
 ## [0.7.0] - 2026-06-12
 
 ### Changed

data/lib/capybara/lightpanda/binary.rb

@@ -33,6 +33,13 @@ module Capybara
 
       DEFAULT_CACHE_TIME = 86_400
 
+      # One-liner that re-provisions the binary from a process with no
+      # HTTP-stubbing loaded (VCR/WebMock guard the test process itself).
+      # Referenced from the stale-fallback warning and BETA_TESTING.md.
+      PROVISION_HINT =
+        "bundle exec ruby -r capybara-lightpanda " \
+        "-e 'Capybara::Lightpanda::Binary.remove; puts Capybara::Lightpanda::Binary.update'"
+
       class << self
         # Set a specific release tag (e.g. "0.3.0") to pin downloads to that
         # release. When nil, the rolling "nightly" tag is used. The pin only
@@ -96,7 +103,36 @@ module Capybara
             return system_path
           end
 
-          download
+          # Stale-or-absent cache, nothing on PATH: refresh from the network.
+          # If that fails (GitHub 5xx, DNS/connect timeouts, SocketError) but a
+          # usable — if stale — binary is already cached, keep using it rather
+          # than hard-failing. A cold cache (nothing on disk) still surfaces the
+          # error. The MINIMUM_NIGHTLY_BUILD floor is enforced downstream in
+          # Process#start, so a sub-floor binary can't slip in.
+          #
+          # Deliberately StandardError, not Exception: WebMock's
+          # NetConnectNotAllowedError descends from Exception so it propagates
+          # through app rescue blocks by design — a test suite that blocks net
+          # connections SHOULD fail loudly here, not silently fall back. CI
+          # pre-provisions the binary outside that guard instead (real-apps.yml).
+          begin
+            download
+          rescue StandardError => e
+            raise unless File.executable?(destination)
+
+            # Kernel.warn, not log: log() is silent unless LIGHTPANDA_DEBUG or
+            # an explicit logger is set, and this fallback is exactly the
+            # moment the user needs to hear about — a VCR-guarded suite (whose
+            # UnhandledHTTPRequestError is a StandardError, unlike raw
+            # WebMock's Exception) lands here silently, keeps a stale binary,
+            # and later hits a confusing MINIMUM_NIGHTLY_BUILD floor error
+            # with no trace of the blocked download.
+            warn("[capybara-lightpanda] Binary download failed (#{e.class}: #{e.message}); " \
+                 "falling back to the cached binary at #{destination}. " \
+                 "If your suite stubs HTTP (VCR/WebMock), pre-provision from an " \
+                 "unstubbed process: #{PROVISION_HINT}")
+            destination
+          end
         end
 
         # Delete the cached binary. Returns the path that was deleted, or nil
@@ -173,9 +209,15 @@ module Capybara
         #   suggest `brew update && brew upgrade lightpanda` (brew pins
         #   each user's binary at install time and doesn't refresh on its
         #   own when the tap publishes a newer nightly).
-        # - Path equals our own cache → suggest the gem's rake tasks; the
-        #   `remove` step is required because `update` honors `cache_time`
-        #   and would otherwise no-op on a too-old-but-not-yet-expired file.
+        # - Path equals our own cache → suggest the require-the-gem one-liner.
+        #   NOT the lightpanda:binary:* rake tasks: in a Rails app the gem
+        #   usually sits in the :test Gemfile group, so the tasks only exist
+        #   under RAILS_ENV=test (the Railtie can't help a plain `bundle exec
+        #   rake` in development), and outside Rails they're never loaded at
+        #   all. The one-liner requires the gem explicitly, so it works from
+        #   any environment. The `remove` step is required because `update`
+        #   honors `cache_time` and would otherwise no-op on a
+        #   too-old-but-not-yet-expired file.
         # - Anything else (user-managed install at a custom path) → keep
         #   the curl-overwrite suggestion, since we don't know how the file
         #   got there.
@@ -183,7 +225,7 @@ module Capybara
           if brew_managed?(binary_path)
             "brew update && brew upgrade lightpanda"
           elsif binary_path == install_path
-            "bundle exec rake lightpanda:binary:remove lightpanda:binary:update"
+            PROVISION_HINT
           else
             "curl -sL #{GITHUB_RELEASE_URL}/nightly/#{platform_binary} " \
               "-o #{binary_path} && chmod +x #{binary_path}"

data/lib/capybara/lightpanda/browser.rb

@@ -77,6 +77,8 @@ module Capybara
         @modal_messages = []
         @modal_messages_mutex = Mutex.new
         @modal_handler_installed = false
+        @console_logs = []
+        @console_logs_mutex = Mutex.new
         @frame_stack = []
         @turbo_event = Utils::Event.new
         @turbo_event.set
@@ -124,6 +126,7 @@ module Capybara
 
         @turbo_event.set
         subscribe_to_console_logs
+        subscribe_to_console_capture
         subscribe_to_execution_context
         subscribe_to_turbo_signals
         subscribe_to_navigation_response
@@ -172,6 +175,7 @@ module Capybara
         @page_events_enabled = false
         @modal_handler_installed = false
         @modal_messages_mutex.synchronize { @modal_messages.clear }
+        @console_logs_mutex.synchronize { @console_logs.clear }
         @last_navigation_response = nil
         @document_request_id = nil
         clear_frames
@@ -588,6 +592,22 @@ module Capybara
         @cookies ||= Cookies.new(self)
       end
 
+      # Console messages captured from `Runtime.consoleAPICalled` since the
+      # last `reset` (Turbo-tracker sentinels excluded). Loose hashes, like
+      # Network#traffic: `{type:, text:, timestamp:, args:}` where `type` is
+      # the console method name ("log", "error", "warning", ...), `text` joins
+      # the arguments' primitive values/descriptions, and `args` keeps the raw
+      # CDP RemoteObjects. Lets suites assert on JS console errors
+      # (`browser.console_logs.select { |m| m[:type] == "error" }`) the way
+      # peer drivers do via custom Ferrum loggers.
+      def console_logs
+        @console_logs_mutex.synchronize { @console_logs.dup }
+      end
+
+      def clear_console_logs
+        @console_logs_mutex.synchronize { @console_logs.clear }
+      end
+
       # -- Frame Support --
       # `frame_stack` (Array<Node>) is the Capybara `switch_to_frame` stack;
       # it drives where `find` resolves selectors. Stored as Nodes so
@@ -640,61 +660,52 @@ module Capybara
         page_command("LP.handleJavaScriptDialog", accept: false)
       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_matching_type_message = nil
         last_seen_message = nil
         claimed = nil
         Utils::Wait.until(timeout: wait, interval: 0.05) do
-          claimed = pop_modal_message(type.to_s, regexp)
+          claimed = pop_modal_message(regexp)
           next true if claimed
 
-          last = peek_last_modal_message(type.to_s)
-          last_matching_type_message = last[:matching_type] || last_matching_type_message
-          last_seen_message = last[:any] || last_seen_message
+          last_seen_message = peek_last_modal_message || last_seen_message
           false
         end
         claimed[:message]
       rescue TimeoutError
-        raise_modal_not_found(type, text, last_matching_type_message, last_seen_message)
+        raise_modal_not_found(type, text, last_seen_message)
       end
 
       private
 
-      # Pop the first queued dialog whose type matches and (when `regexp` is
-      # non-nil) whose message matches the requested pattern. Returns the
-      # entry or nil. Serialized with the message-thread writer.
-      def pop_modal_message(type, regexp)
+      # 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|
-            m[:type] == type && (regexp.nil? || m[:message].to_s.match?(regexp))
+            regexp.nil? || m[:message].to_s.match?(regexp)
           end
           @modal_messages.delete(match) if match
           match
         end
       end
 
-      # Inspect the queue for diagnostics. Returns the most recent message
-      # of the requested type (if any) AND the most recent message of any
-      # type so the failure message can hint at a type mismatch.
-      def peek_last_modal_message(type)
-        @modal_messages_mutex.synchronize do
-          {
-            matching_type: @modal_messages.reverse.find { |m| m[:type] == type }&.dig(:message),
-            any: @modal_messages.last&.dig(:message),
-          }
-        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, matching_type_message, any_message)
-        if matching_type_message
-          raise Capybara::ModalNotFound,
-                "Unable to find modal dialog with #{text} - found '#{matching_type_message}' instead."
-        end
-        if any_message
+      def raise_modal_not_found(type, text, last_seen_message)
+        if last_seen_message
           raise Capybara::ModalNotFound,
-                "Unable to find #{type} modal#{" with #{text}" if text} - " \
-                "a different dialog fired with message '#{any_message}'."
+                "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
@@ -865,6 +876,35 @@ module Capybara
       TURBO_SENTINEL_PREFIX = "__lightpanda_turbo_"
       private_constant :TURBO_SENTINEL_PREFIX
 
+      # Oldest entries are dropped past this cap so a chatty page can't grow
+      # the buffer unbounded across a long session.
+      CONSOLE_LOGS_LIMIT = 1_000
+
+      # Ring-buffer every console.* call for `Browser#console_logs`. Separate
+      # from subscribe_to_console_logs (which streams to an optional IO logger)
+      # so capture works without any logger configured. Skips the Turbo
+      # activity-tracker sentinels — they're driver plumbing, not page output.
+      def subscribe_to_console_capture
+        on("Runtime.consoleAPICalled") do |params|
+          args = params["args"]
+          next unless args.is_a?(Array)
+
+          first = args.first&.dig("value")
+          next if first.is_a?(String) && first.start_with?(TURBO_SENTINEL_PREFIX)
+
+          entry = {
+            type: params["type"],
+            text: args.map { |a| a.fetch("value") { a["description"] }.to_s }.join(" "),
+            timestamp: params["timestamp"],
+            args: args,
+          }
+          @console_logs_mutex.synchronize do
+            @console_logs << entry
+            @console_logs.shift(@console_logs.size - CONSOLE_LOGS_LIMIT) if @console_logs.size > CONSOLE_LOGS_LIMIT
+          end
+        end
+      end
+
       # Wire @turbo_event to the JS-side _signalTurbo emissions. The JS calls
       # console.debug('__lightpanda_turbo_busy') / '_idle' on transitions across
       # zero pending ops; Lightpanda forwards those to Runtime.consoleAPICalled.

data/lib/capybara/lightpanda/cookies.rb

@@ -76,6 +76,8 @@ module Capybara
       def get(name)
         find { |cookie| cookie.name == name }
       end
+      # Ferrum/Cuprite spelling: `browser.cookies["session_id"]`.
+      alias [] get
 
       def set(name:, value:, domain: nil, path: "/", secure: false, http_only: false, # rubocop:disable Metrics/ParameterLists
               same_site: nil, expires: nil)

data/lib/capybara/lightpanda/driver.rb

@@ -213,6 +213,29 @@ module Capybara
         nil
       end
 
+      # capybara-screenshot's fallback for unregistered drivers calls
+      # `driver.render(path)` (the Cuprite/Ferrum spelling). Without the alias
+      # every failed test in a capybara-screenshot suite logged
+      # "Screenshot could not be saved: undefined method 'render'".
+      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
+      # driver, and real suites call them there (page.driver.headers = ...).
+
+      def headers
+        browser.network.extra_headers
+      end
+
+      def headers=(headers)
+        browser.network.headers = headers
+      end
+
+      def add_headers(headers)
+        browser.network.add_headers(headers)
+      end
+
       # -- Lifecycle --
 
       # Thin Cuprite-style wrapper. The interesting work — disposing the

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

@@ -1,19 +1,6 @@
 (function() {
   if (window._lightpanda) return;
 
-  // --- readystatechange re-dispatch (upstream gap, wishlist A36) ---
-  // Lightpanda transitions document.readyState correctly but never fires the
-  // readystatechange event. Turbo's PageObserver listens ONLY for that event
-  // to reach pageLoaded() — without it, turbo:load never fires. Re-dispatch
-  // from the two lifecycle events Lightpanda does fire: DOMContentLoaded
-  // (readyState=interactive) and window load (readyState=complete).
-  // Drop this block once the upstream fix is covered by MINIMUM_NIGHTLY_BUILD.
-  function _fireReadyStateChange() {
-    document.dispatchEvent(new Event('readystatechange'));
-  }
-  document.addEventListener('DOMContentLoaded', _fireReadyStateChange);
-  window.addEventListener('load', _fireReadyStateChange);
-
   // --- Turbo activity tracking ---
   // Tracks pending Turbo operations so the driver can wait for Turbo to settle.
   // Inspired by the CapybaraLockstep approach for stabilizing Turbo integration tests.

data/lib/capybara/lightpanda/network.rb

@@ -55,6 +55,9 @@ module Capybara
         @enabled = false
       end
 
+      # Headers applied via headers= / add_headers. Backs Driver#headers.
+      def extra_headers = @extra_headers || {}
+
       # Setting extra headers also lazily enables the Network domain. Without
       # this, headers were silently ignored until the caller separately ran
       # `network.enable` (or `wait_for_network_idle`). Cuprite/Ferrum parity.

data/lib/capybara/lightpanda/node.rb

@@ -485,6 +485,13 @@ module Capybara
       CLICK_JS = <<~JS
         function() {
           var EventCtor = (typeof MouseEvent !== 'undefined') ? MouseEvent : Event;
+          // Real pointer clicks are a mousedown -> mouseup -> click sequence,
+          // and widgets like select2 open on `mousedown`, not `click`.
+          // Cancelling mousedown suppresses focus/text-selection in a real
+          // browser but never the click, so the click below is dispatched
+          // unconditionally.
+          this.dispatchEvent(new EventCtor('mousedown', { bubbles: true, cancelable: true }));
+          this.dispatchEvent(new EventCtor('mouseup', { bubbles: true, cancelable: true }));
           var clickEvt = new EventCtor('click', { bubbles: true, cancelable: true });
           var notCancelled = this.dispatchEvent(clickEvt);
           if (!notCancelled || clickEvt.defaultPrevented) return;

data/lib/capybara/lightpanda/process.rb

@@ -90,10 +90,16 @@ module Capybara
       # DragEvent, merged 2026-06-10) provides the APIs Node#drop's DROP_JS
       # assembles its payload from; on builds without it the drop JS raises
       # "DataTransfer is not defined".
-      # Build 6699 = the #2671 merge (d1f4c409, 2026-06-10) — now the binding
-      # floor. (The prior 6672 file-upload floor — and 6353 before it — are
-      # subsumed.)
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6699")
+      # Build 6699 = the #2671 merge (d1f4c409, 2026-06-10) — the Node#drop
+      # DataTransfer floor. (The prior 6672 file-upload floor — and 6353
+      # before it — are subsumed.)
+      # PR #2708 (document fires readystatechange on readiness changes,
+      # merged 2026-06-12) made the index.js readystatechange re-dispatch
+      # shim redundant, so it was removed — on builds without #2708 Turbo's
+      # PageObserver never reaches pageLoaded() and turbo:load never fires.
+      # Build 6736 = first published nightly carrying the #2708 merge — now
+      # the binding floor.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6736")
 
       attr_reader :pid, :ws_url, :version, :nightly_build
 

data/lib/capybara/lightpanda/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    # Exposes the gem's rake tasks (lightpanda:binary:*) inside Rails apps.
+    # Without this, the BinaryError remediation hint ("bundle exec rake
+    # lightpanda:binary:remove lightpanda:binary:update") pointed at tasks
+    # that didn't exist in the app's rake namespace.
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path("tasks/binary.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.7.0"
+    VERSION = "0.8.0"
   end
 end

data/lib/capybara-lightpanda.rb

@@ -21,6 +21,7 @@ require_relative "capybara/lightpanda/auto_scripts"
 require_relative "capybara/lightpanda/node"
 require_relative "capybara/lightpanda/element_extension"
 require_relative "capybara/lightpanda/driver"
+require_relative "capybara/lightpanda/railtie" if defined?(Rails::Railtie)
 
 module Capybara
   module Lightpanda

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Navid Emad
@@ -89,6 +89,7 @@ files:
 - lib/capybara/lightpanda/node.rb
 - lib/capybara/lightpanda/options.rb
 - lib/capybara/lightpanda/process.rb
+- lib/capybara/lightpanda/railtie.rb
 - lib/capybara/lightpanda/tasks/binary.rake
 - lib/capybara/lightpanda/utils/attempt.rb
 - lib/capybara/lightpanda/utils/event.rb