capybara-lightpanda 0.1.0 → 0.2.0

data/lib/capybara/lightpanda/node.rb

@@ -246,8 +246,6 @@ module Capybara
         raise ObsoleteNode.new(self, "Node is no longer attached to the document")
       end
 
-      # Trigger implicit form submission via the IMPLICIT_SUBMIT_JS pipeline
-      # (same fetch+swap as CLICK_JS, but without a submitter).
       def implicit_submit
         call(IMPLICIT_SUBMIT_JS)
         driver.browser.wait_for_idle
@@ -277,7 +275,7 @@ module Capybara
       # HTML implicit-submission: a trailing \n in a text-like input is like the
       # user pressing Enter — submits the form when there's a default submit
       # button OR exactly one text control. Strip the \n, set the value, then
-      # route through IMPLICIT_SUBMIT_JS so CLICK_JS's fetch+swap runs.
+      # trigger submission via IMPLICIT_SUBMIT_JS.
       def fill_text_input(type, str)
         if str.end_with?("\n") && TEXT_LIKE_INPUT_TYPES.include?(type)
           call(SET_VALUE_JS, truncate_to_maxlength(str.chomp))
@@ -341,13 +339,6 @@ module Capybara
         driver.browser.with_default_context_wait do
           driver.browser.call_function_on(@remote_object_id, function_declaration, *args)
         end
-      rescue BrowserError => e
-        case e.message
-        when /MouseEventFailed/i
-          raise MouseEventFailed.new(self, e.response&.dig("message"))
-        else
-          raise
-        end
       rescue JavaScriptError => e
         case e.class_name
         when "InvalidSelector"
@@ -355,150 +346,16 @@ module Capybara
         else
           raise
         end
+      rescue BrowserError => e
+        case e.message
+        when /MouseEventFailed/i
+          raise MouseEventFailed.new(self, e.response&.dig("message"))
+        else
+          raise
+        end
       end
 
-      # Form-submit click bypass for Lightpanda.
-      #
-      # Lightpanda's `form.submit()` does NOT navigate — it parses, validates, but
-      # never issues an HTTP request. And `document.write()` is a no-op (verified
-      # 2026-04-26: body length unchanged after open/write/close). So both the
-      # native submit path and the previous `fetch+document.write` workaround leave
-      # the page on the original URL with the form still rendered.
-      #
-      # For submit-button clicks we instead `fetch` the form action ourselves,
-      # parse the response with `DOMParser`, swap `document.body.innerHTML`, and
-      # `history.replaceState` the response URL. `_lightpanda` and the XPath
-      # polyfill survive the swap because we don't reload the document.
-      #
-      # For non-submit elements (links, regular buttons, anchors) we fall through
-      # to native `this.click()`. Turbo Drive's click handler — when Turbo is
-      # loaded — intercepts that natively, runs its own fetch+replaceWith, and
-      # works fine on Lightpanda after the `#id` rewriter polyfill in index.js.
-      CLICK_JS = <<~JS
-        function() {
-          var tag = this.tagName.toLowerCase();
-          var type = (this.type || '').toLowerCase();
-          // <button> with no `type` attribute defaults to submit per HTML.
-          var isSubmitBtn = (tag === 'button' && (type === '' || type === 'submit')) ||
-                            (tag === 'input' && (type === 'submit' || type === 'image'));
-          var form = isSubmitBtn ? this.form : null;
-          // Lightpanda doesn't propagate label clicks to their associated
-          // form control the way browsers do, so when Capybara clicks a
-          // <label> for a hidden checkbox/radio (automatic_label_click)
-          // we explicitly forward the click.
-          if (tag === 'label') {
-            this.click();
-            var ctrl = null;
-            var forId = this.getAttribute('for');
-            if (forId) ctrl = this.ownerDocument.getElementById(forId);
-            if (!ctrl) ctrl = this.querySelector('input, select, textarea');
-            if (ctrl) {
-              var ctype = (ctrl.type || '').toLowerCase();
-              if (ctype === 'checkbox' || ctype === 'radio') ctrl.click();
-            }
-            return;
-          }
-          if (!form) {
-            this.click();
-            // Lightpanda doesn't toggle <details> when its <summary> is clicked.
-            // Walk up to the nearest <details> (only if click hit a summary
-            // and we haven't been preventDefault'd by user JS) and flip `open`.
-            if (tag === 'summary') {
-              var d = this.parentNode;
-              while (d && d.nodeType === 1 && d.tagName.toLowerCase() !== 'details') {
-                d = d.parentNode;
-              }
-              if (d && d.tagName && d.tagName.toLowerCase() === 'details') {
-                d.open = !d.open;
-              }
-            }
-            return;
-          }
-
-          // Fire the submit event first so user JS handlers can intercept and
-          // preventDefault — but skip this when Turbo is loaded, because Turbo's
-          // submit pipeline throws on Lightpanda (and the gem already handles the
-          // navigation below). Turbo's link-click pipeline still works fine.
-          if (typeof Turbo === 'undefined') {
-            var ev;
-            if (typeof SubmitEvent === 'function') {
-              ev = new SubmitEvent('submit', { bubbles: true, cancelable: true, submitter: this });
-            } else {
-              ev = new Event('submit', { bubbles: true, cancelable: true });
-              ev.submitter = this;
-            }
-            var allowed = form.dispatchEvent(ev);
-            if (!allowed) return;
-          }
-
-          // No handler intercepted — fetch + swap ourselves because Lightpanda's
-          // native form.submit() does not navigate.
-          // Pass the submitter so the button is serialized at its document
-          // position alongside the form's other named controls.
-          var formData;
-          try { formData = new FormData(form, this); }
-          catch (e) { formData = new FormData(form); }
-          var submitterName = this.getAttribute('name');
-          if (submitterName && !formData.has(submitterName)) {
-            // Lightpanda's FormData(form, submitter) may omit a <button> with no
-            // explicit value attribute; HTML says the value falls back to
-            // textContent, so feed that in ourselves when the entry is missing.
-            var submitterValue = this.getAttribute('value');
-            if (submitterValue === null) {
-              submitterValue = (tag === 'button') ? (this.textContent || '') : '';
-            }
-            formData.append(submitterName, submitterValue);
-          }
-
-          var action = this.getAttribute('formaction') || form.getAttribute('action') || window.location.href;
-          try { action = new URL(action, window.location.href).href; } catch (e) {}
-          var method = (this.getAttribute('formmethod') || form.getAttribute('method') || 'GET').toUpperCase();
-
-          var enctype = (this.getAttribute('formenctype') ||
-                         form.getAttribute('enctype') ||
-                         'application/x-www-form-urlencoded').toLowerCase();
-          // Lightpanda's URLSearchParams.toString() drops the `=` when the value
-          // is an empty string (`{key: ""}` serializes as `key`, not `key=`),
-          // which makes the server parse the field as nil instead of "". Lightpanda
-          // also doesn't perform the HTML-spec LF→CRLF normalization for textarea
-          // values during form submission. Build the query string by hand so both
-          // round-trip correctly.
-          var formEncode = function(fd) {
-            var pairs = [];
-            for (var entry of fd.entries()) {
-              var value = entry[1];
-              if (typeof value === 'string') {
-                // Normalize line endings to CRLF per HTML form-data set spec.
-                value = value.replace(/\\r\\n|\\r|\\n/g, '\\r\\n');
-              }
-              pairs.push(encodeURIComponent(entry[0]).replace(/%20/g, '+') +
-                         '=' +
-                         encodeURIComponent(value).replace(/%20/g, '+'));
-            }
-            return pairs.join('&');
-          };
-          var opts = { method: method, credentials: 'same-origin', redirect: 'follow' };
-          if (method === 'GET') {
-            var sep = action.indexOf('?') >= 0 ? '&' : '?';
-            action = action + sep + formEncode(formData);
-          } else if (enctype === 'multipart/form-data') {
-            // Pass FormData directly — fetch sets Content-Type with the correct boundary.
-            opts.body = formData;
-          } else {
-            opts.headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
-            opts.body = formEncode(formData);
-          }
-
-          return fetch(action, opts).then(function(r) {
-            return r.text().then(function(html) { return { url: r.url, html: html }; });
-          }).then(function(o) {
-            var doc = new DOMParser().parseFromString(o.html, 'text/html');
-            document.title = (doc.title || '');
-            document.body.innerHTML = doc.body.innerHTML;
-            try { history.replaceState(null, '', o.url); } catch (e) {}
-          });
-        }
-      JS
+      CLICK_JS = "function() { this.click() }"
 
       VISIBLE_JS = "function() { return _lightpanda.isVisible(this); }"
 
@@ -548,77 +405,25 @@ module Capybara
         }
       JS
 
-      # HTML implicit-submission: when the user presses Enter in a text-like
-      # field, the form is submitted if either (a) there's a default submit
-      # button, or (b) the form has exactly one submittable text control.
-      # `this` is the input. Mirror CLICK_JS's submit pipeline so the gem's
-      # fetch+swap path runs (Lightpanda's form.submit() doesn't navigate).
+      # HTML implicit-submission: a trailing \n in a text-like input acts like
+      # pressing Enter — submits the form if it has a default submit button OR
+      # exactly one submittable text control. Click the default button (so
+      # click handlers fire) or fall back to `form.requestSubmit()` so the
+      # `submit` event still dispatches.
       IMPLICIT_SUBMIT_JS = <<~JS
         function() {
           var form = this.form;
           if (!form) return;
-          var hasDefault = !!form.querySelector(
+          var btn = form.querySelector(
             'button[type=submit], button:not([type]), input[type=submit], input[type=image]'
           );
-          if (!hasDefault) {
-            var textInputs = form.querySelectorAll(
-              'input[type=text], input[type=email], input[type=password], ' +
-              'input[type=url], input[type=tel], input[type=search], ' +
-              'input[type=number], input:not([type])'
-            );
-            if (textInputs.length !== 1) return;
-          }
-
-          if (typeof Turbo === 'undefined') {
-            var ev;
-            if (typeof SubmitEvent === 'function') {
-              ev = new SubmitEvent('submit', { bubbles: true, cancelable: true });
-            } else {
-              ev = new Event('submit', { bubbles: true, cancelable: true });
-            }
-            var allowed = form.dispatchEvent(ev);
-            if (!allowed) return;
-          }
-
-          var formData = new FormData(form);
-          var action = form.getAttribute('action') || window.location.href;
-          try { action = new URL(action, window.location.href).href; } catch (e) {}
-          var method = (form.getAttribute('method') || 'GET').toUpperCase();
-          var enctype = (form.getAttribute('enctype') || 'application/x-www-form-urlencoded').toLowerCase();
-
-          var formEncode = function(fd) {
-            var pairs = [];
-            for (var entry of fd.entries()) {
-              var value = entry[1];
-              if (typeof value === 'string') {
-                value = value.replace(/\\r\\n|\\r|\\n/g, '\\r\\n');
-              }
-              pairs.push(encodeURIComponent(entry[0]).replace(/%20/g, '+') +
-                         '=' +
-                         encodeURIComponent(value).replace(/%20/g, '+'));
-            }
-            return pairs.join('&');
-          };
-
-          var opts = { method: method, credentials: 'same-origin', redirect: 'follow' };
-          if (method === 'GET') {
-            var sep = action.indexOf('?') >= 0 ? '&' : '?';
-            action = action + sep + formEncode(formData);
-          } else if (enctype === 'multipart/form-data') {
-            opts.body = formData;
-          } else {
-            opts.headers = { 'Content-Type': 'application/x-www-form-urlencoded' };
-            opts.body = formEncode(formData);
-          }
-
-          return fetch(action, opts).then(function(r) {
-            return r.text().then(function(html) { return { url: r.url, html: html }; });
-          }).then(function(o) {
-            var doc = new DOMParser().parseFromString(o.html, 'text/html');
-            document.title = (doc.title || '');
-            document.body.innerHTML = doc.body.innerHTML;
-            try { history.replaceState(null, '', o.url); } catch (e) {}
-          });
+          if (btn) { btn.click(); return; }
+          var textInputs = form.querySelectorAll(
+            'input[type=text], input[type=email], input[type=password], ' +
+            'input[type=url], input[type=tel], input[type=search], ' +
+            'input[type=number], input:not([type])'
+          );
+          if (textInputs.length === 1) form.requestSubmit();
         }
       JS
 

data/lib/capybara/lightpanda/options.rb

@@ -7,17 +7,24 @@ module Capybara
     class Options
       DEFAULT_TIMEOUT = ENV.fetch("LIGHTPANDA_DEFAULT_TIMEOUT", 15).to_i
       DEFAULT_PROCESS_TIMEOUT = ENV.fetch("LIGHTPANDA_PROCESS_TIMEOUT", 10).to_i
+      # Bounded budget for the WebSocket TCP+Upgrade handshake. Distinct from
+      # `timeout` (per-CDP-command budget) because a handshake either succeeds
+      # in a few hundred ms or won't — bleeding the full command budget into
+      # it just delays the eventual failure.
+      DEFAULT_HANDSHAKE_TIMEOUT = ENV.fetch("LIGHTPANDA_HANDSHAKE_TIMEOUT", 5).to_i
       DEFAULT_HOST = "127.0.0.1"
       DEFAULT_PORT = 9222
       DEFAULT_WINDOW_SIZE = [1024, 768].freeze
 
-      attr_accessor :host, :port, :timeout, :process_timeout, :window_size, :browser_path, :headless, :logger
+      attr_accessor :host, :port, :timeout, :handshake_timeout, :process_timeout,
+                    :window_size, :browser_path, :headless, :logger
       attr_writer :ws_url
 
       def initialize(options = {})
         @host = options.fetch(:host, DEFAULT_HOST)
         @port = options.fetch(:port, DEFAULT_PORT)
         @timeout = options.fetch(:timeout, DEFAULT_TIMEOUT)
+        @handshake_timeout = options.fetch(:handshake_timeout, DEFAULT_HANDSHAKE_TIMEOUT)
         @process_timeout = options.fetch(:process_timeout, DEFAULT_PROCESS_TIMEOUT)
         @window_size = options.fetch(:window_size, DEFAULT_WINDOW_SIZE)
         @browser_path = options[:browser_path]
@@ -39,6 +46,7 @@ module Capybara
           host: host,
           port: port,
           timeout: timeout,
+          handshake_timeout: handshake_timeout,
           process_timeout: process_timeout,
           window_size: window_size,
           browser_path: browser_path,

data/lib/capybara/lightpanda/process.rb

@@ -1,14 +1,31 @@
 # frozen_string_literal: true
 
+require "open3"
+
 module Capybara
   module Lightpanda
     class Process
-      READY_PATTERN = /server running.*address=(\d+\.\d+\.\d+\.\d+:\d+)/
+      READY_PATTERN = /server running.*address\s*=\s*(\d+\.\d+\.\d+\.\d+:\d+)/m
       ADDRESS_IN_USE_PATTERN = /err=AddressInUse/
 
-      # First nightly with Page.addScriptToEvaluateOnNewDocument (PR #1993, merged 2026-03-30).
-      # The gem relies on this for XPath polyfill auto-injection.
-      MINIMUM_NIGHTLY_BUILD = 5267
+      # Floor for the cookie/navigation/redirect/modal/keyboard/css/forms
+      # fixes the gem now relies on: PR #2255 (Network.clearBrowserCookies
+      # empty params + Network.getAllCookies), PR #2257
+      # (window.location.pathname/.search assignment triggers navigation),
+      # PR #2265 (URL fragment inherited across fragment-less redirect),
+      # PR #2261 (LP.handleJavaScriptDialog pre-arm), PR #2283 (Referer on
+      # cross-page nav), PR #2292 (KeyboardEvent.keyCode/charCode), PR #2294
+      # (UA stylesheet display:none for HEAD/SCRIPT/STYLE/NOSCRIPT/TEMPLATE/
+      # TITLE/[type=hidden]), PR #2308 (textarea LF→CRLF), PR #2312 (<input
+      # type=image> click submits form), PR #2315 (:disabled honors fieldset/
+      # optgroup ancestors), PR #2322 (LP dialog defaultText fallback when
+      # promptText is null), PR #2324 (<label> click runs activation behavior
+      # on labeled control), PR #2286 (HTML constraint validation API:
+      # el.validity, validationMessage, checkValidity, reportValidity),
+      # PR #2342 (<summary> click toggles parent <details>.open). Build
+      # 6005 = main HEAD 0420802f (2026-05-04); ships in nightly published
+      # 2026-05-04 03:44 UTC for all four platforms.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6005")
 
       attr_reader :pid, :ws_url, :version, :nightly_build
 
@@ -76,14 +93,17 @@ module Capybara
       def check_minimum_version(binary_path)
         stdout, = Open3.capture3(binary_path, "version")
         @version = stdout.strip
-        @nightly_build = @version[/nightly\.(\d+)/, 1]&.to_i
+        # Accept either `nightly.NNNN` (publicly distributed builds) or
+        # `dev.NNNN` (locally compiled trees) — the build number is the same
+        # `git rev-list --count HEAD` counter, just labelled differently.
+        build = @version[/(?:nightly|dev)\.(\d+)/, 1]
+        @nightly_build = Gem::Version.new(build) if build
 
         return if @nightly_build && @nightly_build >= MINIMUM_NIGHTLY_BUILD
 
         raise BinaryError,
               "Lightpanda #{@version} is too old. " \
-              "This gem requires nightly build >= #{MINIMUM_NIGHTLY_BUILD} " \
-              "(Page.addScriptToEvaluateOnNewDocument support). " \
+              "This gem requires build >= #{MINIMUM_NIGHTLY_BUILD}. " \
               "Update: curl -sL https://github.com/lightpanda-io/browser/releases/download/nightly/" \
               "#{Binary.platform_binary} -o #{binary_path} && chmod +x #{binary_path}"
       rescue Errno::ENOENT
@@ -204,17 +224,22 @@ module Capybara
         @pid = nil
       end
 
+      # Auto-recover when a previous Lightpanda is still bound to our port.
+      # Best-effort: relies on `lsof` to map port → pid (macOS / most Linux
+      # distros). Where `lsof` isn't on PATH, we surface a clear error rather
+      # than silently failing the retry — the user can free the port manually.
       def kill_process_on_port(port)
         port = port.to_i
         return if port <= 0
 
-        pids = `lsof -ti tcp:#{port} 2>/dev/null`.strip
-        return if pids.empty?
-
-        pids.split("\n").each do |pid_str|
-          pid = pid_str.strip.to_i
-          next if pid <= 0
+        pids = pids_listening_on(port)
+        if pids.nil?
+          raise BinaryError,
+                "Port #{port} is in use and `lsof` is unavailable to identify the holder. " \
+                "Free the port manually or install lsof to enable automatic recovery."
+        end
 
+        pids.each do |pid|
           ::Process.kill("TERM", pid)
         rescue Errno::ESRCH, Errno::EPERM
           nil
@@ -223,6 +248,20 @@ module Capybara
         sleep 0.5
       end
 
+      # Returns an array of PIDs holding the TCP port, [] if none, or nil if
+      # `lsof` itself isn't available on this system.
+      def pids_listening_on(port)
+        stdout, _, status = Open3.capture3("lsof", "-ti", "tcp:#{port}")
+        return [] unless status.success?
+
+        stdout.split("\n").filter_map do |line|
+          pid = line.strip.to_i
+          pid.positive? ? pid : nil
+        end
+      rescue Errno::ENOENT
+        nil
+      end
+
       # Class method so the finalizer proc doesn't capture `self` (which
       # would prevent GC from ever running the finalizer).
       class << self

data/lib/capybara/lightpanda/utils/attempt.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    module Utils
+      # Generic retry helper for transient CDP-class errors. Mirrors ferrum's
+      # Utils::Attempt — extracted so callsites don't have to rebuild the
+      # rescue/sleep loop. Default `max` and `wait` match ferrum's
+      # INTERMITTENT_ATTEMPTS / INTERMITTENT_SLEEP so behavior is predictable
+      # across the two ecosystems.
+      module Attempt
+        INTERMITTENT_ATTEMPTS = 6
+        INTERMITTENT_SLEEP = 0.1
+
+        def self.with_retry(errors:, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP)
+          attempts = 0
+          begin
+            yield
+          rescue *Array(errors)
+            attempts += 1
+            raise if attempts >= max
+
+            sleep wait
+            retry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/capybara-lightpanda.rb

@@ -9,6 +9,7 @@ require_relative "capybara/lightpanda/options"
 require_relative "capybara/lightpanda/binary"
 require_relative "capybara/lightpanda/process"
 require_relative "capybara/lightpanda/utils/event"
+require_relative "capybara/lightpanda/utils/attempt"
 require_relative "capybara/lightpanda/client"
 require_relative "capybara/lightpanda/network"
 require_relative "capybara/lightpanda/cookies"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Navid Emad
@@ -87,6 +87,7 @@ files:
 - lib/capybara/lightpanda/node.rb
 - lib/capybara/lightpanda/options.rb
 - lib/capybara/lightpanda/process.rb
+- lib/capybara/lightpanda/utils/attempt.rb
 - lib/capybara/lightpanda/utils/event.rb
 - lib/capybara/lightpanda/version.rb
 - lib/capybara/lightpanda/xpath_polyfill.rb