capybara-lightpanda 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42246ea44b80c592e6779cf2aa95890c7635fb057b0061064b63bf15004dcde6
-  data.tar.gz: 63131038538438b32d39d8e46a36005df0306e8daadaa38ff88540874c6c46aa
+  metadata.gz: 9bb84252bec4e22492ad1e2165a63842c3fad60ab9d80ee0df60db55c2425c9a
+  data.tar.gz: '090fbdca94bf7e482dda301a2aad4b51065211972bff4a06a9aa3e848a2a9ef4'
 SHA512:
-  metadata.gz: 1728491bdd3d3dac24559cc663ee250af16f90d7944d2c27be0b879ddbfc23a2a00181f39970d7622fd1b640449d97c7d373c4f6a414aae9073dc0f3cf92d1f8
-  data.tar.gz: 47e0408c55b5150347656d8136b6dc993b39d38a051a39efec480e2d913cf799f45c18242fd031bbb6962f79b7a39d63cc2eec8d2c14e2f42f34ed3b029af867
+  metadata.gz: 3bf39418c02c38ead4fc8ead897064730711d97bcd2e787d049ae1860e89bcf07e155f4ebb3743263e4c531250935d73e02ae768196aa5d27e205f8c3f903d1e
+  data.tar.gz: 145951b47b0ef2ce55e4c02932c006efdaa48fd6ac556daf5a18fef5949d63ebf861eabf262a93bb1a2a51dcc46b89d9d510fcbcc5c38fc7153dc1a0cd24402b

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.3.0] - 2026-05-12
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6109 (published 2026-05-12). The driver refuses to start against older binaries.
+
+### Fixed
+
+- Iframe tests no longer crash with `NoExecutionContextError` when the page inside the iframe navigates. `switch_to_frame` and `within_frame` now re-resolve the iframe element on a stale-handle error and retry once, so multi-step flows inside an `<iframe>` (logins, embedded checkouts, OAuth dialogs) stay stable across child-frame navigations.
+- Clicking a submit button no longer fires `submit` twice. On Turbo Drive pages this previously produced duplicate `turbo:submit-start` events and could abort the real fetch mid-flight.
+
+### Removed
+
+- The gem no longer ships its own XPath engine — Lightpanda evaluates XPath natively now, including the full XPath 1.0 selector surface. `find(:xpath, …)`, Capybara's automatic XPath fallback, and any custom XPath finders all keep working unchanged; the same behavior, with ~750 fewer lines injected per test process.
+- The gem's JavaScript shim for `back` / `forward` is gone. Navigation history now routes through Lightpanda directly, which is more reliable across navigation crashes.
+
+## [0.2.2] - 2026-05-06
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6065 (published 2026-05-06). The driver refuses to start against older binaries.
+
+### Fixed
+
+- Turbo Drive `<form>` submissions now intercept correctly. Forms inside a
+  Hotwire / Turbo Drive page no longer crash on submit, and Turbo's `submit`
+  interceptors fire as they should — `click_button`, `find('form').submit`,
+  and Enter-key implicit submission all complete end-to-end.
+- `evaluate_script` and `execute_script` calls with top-level `const` / `let`
+  no longer collide across calls. Consecutive scripts that each declare the
+  same identifier used to fail with `Identifier 'foo' has already been
+  declared`; they're now isolated. `execute_script` also now raises on
+  JavaScript errors instead of silently swallowing them.
+- Same-document fragment-only `<a href="#…">` clicks update the URL hash
+  instead of triggering a real navigation. Tests that drive DOM updates from
+  an anchor click no longer lose pending `setTimeout` callbacks or have form
+  values cleared from under them.
+- `body` returns an empty string rather than crashing during the brief window
+  after `reset_session!` when the new session has a target but no document yet.
+- Stale element references during cross-document navigation now resolve to
+  `nil` internally instead of bubbling a browser error up to your test,
+  letting Capybara's automatic-reload pick a fresh element.
+
+### Internal
+
+- One internal polyfill removed: Lightpanda now matches the spec when a DOM
+  event listener throws (a throwing listener no longer halts the rest of the
+  bubble walk), so the gem doesn't need to compensate. No code change required
+  on your end.
+
 ## [0.2.1] - 2026-05-05
 
 ### Fixed

data/lib/capybara/lightpanda/browser.rb

@@ -35,6 +35,7 @@ module Capybara
         @modal_messages = []
         @modal_handler_installed = false
         @frame_stack = []
+        @frame_locators = []
         @frames = Concurrent::Hash.new
         @turbo_event = Utils::Event.new
         @turbo_event.set
@@ -108,7 +109,7 @@ module Capybara
         @page_events_enabled = false
         @modal_handler_installed = false
         @modal_messages.clear
-        @frame_stack.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
@@ -153,7 +154,7 @@ module Capybara
         @target_id = nil
         @session_id = nil
         @modal_handler_installed = false
-        @frame_stack.clear
+        clear_frames
       end
 
       def command(method, **params)
@@ -217,11 +218,11 @@ module Capybara
       end
 
       def back
-        wait_for_navigation { execute("history.back()") }
+        wait_for_navigation { navigate_history(-1) }
       end
 
       def forward
-        wait_for_navigation { execute("history.forward()") }
+        wait_for_navigation { navigate_history(+1) }
       end
 
       def refresh
@@ -238,7 +239,11 @@ module Capybara
       end
 
       def body
-        evaluate("document.documentElement.outerHTML")
+        # Guard against the brief window after a fresh BrowserContext / target
+        # is created where the V8 context exists but `document.documentElement`
+        # is still null. Hit by Capybara's `#reset_session! resets page body`
+        # spec since the 0.2.0 Ferrum-style reset rewrite.
+        evaluate("(document.documentElement && document.documentElement.outerHTML) || ''")
       end
       alias html body
 
@@ -247,9 +252,25 @@ module Capybara
       # and dispatch via Runtime.callFunctionOn so `arguments[i]` is bound.
       # Both paths use `returnByValue: false` and unwrap so DOM-node returns
       # come back as `{ "__lightpanda_node__" => ... }` for the Driver to wrap.
+      #
+      # Even the no-args path wraps the expression in an IIFE to isolate
+      # top-level `const`/`let` declarations. Upstream Lightpanda retains
+      # those bindings across `Runtime.evaluate` calls (V8 starts each call
+      # with fresh lexical scope per spec), so a second `const sel = ...`
+      # raises `SyntaxError: Identifier 'sel' has already been declared`.
+      # Wrapping pushes the declarations into a function scope that gets
+      # discarded when the IIFE returns.
+      #
+      # Use direct `eval` inside the IIFE so the user's text can be a bare
+      # expression (`'foo'`), a `throw` statement, OR a multi-statement
+      # script with `const`/`let`. `eval`'s completion-value semantics
+      # return the last expression's value in all cases. A naive
+      # `return EXPR;` wrap would syntax-error on `throw …` and on
+      # multi-statement scripts.
       def evaluate(expression, *args)
         if args.empty?
-          response = page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: true)
+          wrapped = "(function(){return eval(#{expression.to_json})})()"
+          response = page_command("Runtime.evaluate", expression: wrapped, returnByValue: false, awaitPromise: true)
           if response["exceptionDetails"]
             debug_js_failure("evaluate", expression, response)
             raise JavaScriptError, response
@@ -263,9 +284,20 @@ module Capybara
       end
 
       # Execute JS without returning a value.
+      #
+      # Like `evaluate`, the no-args path wraps in an IIFE — same upstream
+      # `const`/`let` leak. Also raises on JS exceptions so silent
+      # failures don't mask test bugs (the previous fast path swallowed them
+      # because `awaitPromise: false` was checked but `exceptionDetails` was
+      # not).
       def execute(expression, *args)
         if args.empty?
-          page_command("Runtime.evaluate", expression: expression, returnByValue: false, awaitPromise: false)
+          wrapped = "(function(){#{expression}})()"
+          response = page_command("Runtime.evaluate", expression: wrapped, returnByValue: false, awaitPromise: false)
+          if response["exceptionDetails"]
+            debug_js_failure("execute", expression, response)
+            raise JavaScriptError, response
+          end
           return nil
         end
 
@@ -497,13 +529,16 @@ module Capybara
 
       def push_frame(node)
         @frame_stack.push(node)
+        @frame_locators.push(capture_frame_locator(node))
       end
 
       def pop_frame
+        @frame_locators.pop
         @frame_stack.pop
       end
 
       def clear_frames
+        @frame_locators.clear
         @frame_stack.clear
       end
 
@@ -601,16 +636,26 @@ module Capybara
       INVALID_SELECTOR_MARKER = "LIGHTPANDA_INVALID_SELECTOR:"
 
       # JS function for finding elements within a node.
-      # Works in any execution context (top frame or iframe). Any throw from
-      # querySelectorAll means the selector is malformed (the spec only allows
-      # SYNTAX_ERR DOMException; Lightpanda's V8 currently throws a generic
-      # Error with messages like "InvalidClassSelector"). Re-throw with the
-      # marker prefix so Ruby converts to InvalidSelector regardless.
+      # Works in any execution context (top frame or iframe). For CSS, any
+      # throw from querySelectorAll means the selector is malformed
+      # (re-throw with the marker prefix so Ruby converts to InvalidSelector).
+      # XPath routes through native `Document.evaluate` + `XPathResult`
+      # (Lightpanda PR #2305, in nightly >=6109); on parse error we return
+      # [] silently to match Capybara's internal XPath generator, which
+      # sometimes produces selectors with empty trailing predicates like
+      # `(...)[]` that native rejects but `has_element?` expects to behave
+      # as "not found" rather than raise InvalidSelector.
+      # `XPathResult.ORDERED_NODE_SNAPSHOT_TYPE` is `7` in the spec — inlined
+      # so the JS doesn't depend on the enum being defined as a constant.
       FIND_WITHIN_JS = <<~JS.freeze
         function(method, selector) {
           if (method === 'xpath') {
-            if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, this);
-            return [];
+            try {
+              var r = this.ownerDocument.evaluate(selector, this, null, 7, null);
+              var nodes = [];
+              for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+              return nodes;
+            } catch(e) { return []; }
           }
           try { return Array.from(this.querySelectorAll(selector)); }
           catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
@@ -625,8 +670,12 @@ module Capybara
           try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
           if (!doc) return [];
           if (method === 'xpath') {
-            if (typeof _lightpanda !== 'undefined') return _lightpanda.xpathFind(selector, doc);
-            return [];
+            try {
+              var r = doc.evaluate(selector, doc, null, 7, null);
+              var nodes = [];
+              for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+              return nodes;
+            } catch(e) { return []; }
           }
           try { return Array.from(doc.querySelectorAll(selector)); }
           catch(e) { throw new Error('#{INVALID_SELECTOR_MARKER}' + selector); }
@@ -634,14 +683,97 @@ module Capybara
       JS
       private_constant :FIND_IN_FRAME_JS
 
+      # Captures identifying attributes of an iframe element at push_frame
+      # time so we can re-resolve it later if its contextId is churned by
+      # lightpanda-io/browser#2400. id/name/src are tried in order; `index`
+      # (position among iframes in the owning document) is the last-resort
+      # fallback when none of the attributes is present.
+      CAPTURE_FRAME_LOCATOR_JS = <<~JS
+        function() {
+          var siblings = this.ownerDocument.querySelectorAll('iframe');
+          var index = -1;
+          for (var i = 0; i < siblings.length; i++) {
+            if (siblings[i] === this) { index = i; break; }
+          }
+          return {
+            id: this.getAttribute('id'),
+            name: this.getAttribute('name'),
+            src: this.getAttribute('src'),
+            index: index,
+          };
+        }
+      JS
+      private_constant :CAPTURE_FRAME_LOCATOR_JS
+
+      # Picks the iframe inside `this.contentDocument` matching a locator
+      # produced by CAPTURE_FRAME_LOCATOR_JS. Used to re-resolve a nested
+      # iframe element when its parent iframe has just been refreshed.
+      RESOLVE_NESTED_IFRAME_JS = <<~JS
+        function(locator) {
+          var doc;
+          try { doc = this.contentDocument || (this.contentWindow && this.contentWindow.document); } catch(e) {}
+          if (!doc) return null;
+          var iframes = doc.querySelectorAll('iframe');
+          for (var i = 0; i < iframes.length; i++) {
+            var f = iframes[i];
+            if (locator.id && f.getAttribute('id') === locator.id) return f;
+            if (locator.name && f.getAttribute('name') === locator.name) return f;
+            if (locator.src && f.getAttribute('src') === locator.src) return f;
+          }
+          if (typeof locator.index === 'number' && locator.index >= 0 && locator.index < iframes.length) {
+            return iframes[locator.index];
+          }
+          return null;
+        }
+      JS
+      private_constant :RESOLVE_NESTED_IFRAME_JS
+
+      # Same shape as RESOLVE_NESTED_IFRAME_JS but reads `document` directly
+      # for the top-level case where `this` is unbound (Runtime.evaluate).
+      RESOLVE_ROOT_IFRAME_JS = <<~JS
+        (function(locator) {
+          var iframes = document.querySelectorAll('iframe');
+          for (var i = 0; i < iframes.length; i++) {
+            var f = iframes[i];
+            if (locator.id && f.getAttribute('id') === locator.id) return f;
+            if (locator.name && f.getAttribute('name') === locator.name) return f;
+            if (locator.src && f.getAttribute('src') === locator.src) return f;
+          }
+          if (typeof locator.index === 'number' && locator.index >= 0 && locator.index < iframes.length) {
+            return iframes[locator.index];
+          }
+          return null;
+        })
+      JS
+      private_constant :RESOLVE_ROOT_IFRAME_JS
+
+      # Lightweight stand-in for a Node when refresh_frame_stack! re-resolves
+      # an iframe. The only field anyone reads off frame_stack entries is
+      # remote_object_id (browser.rb find_in_frame, driver.rb frame_url /
+      # frame_title), so a Struct with that one field is sufficient and
+      # avoids constructing real Node instances (which need a Driver ref).
+      FrameRef = Struct.new(:remote_object_id)
+      private_constant :FrameRef
+
       def find_in_document(method, selector)
         with_default_context_wait do
           # Coerce Symbol selectors (e.g. Capybara warning path lets `have_css(:p)`
           # through) to a string before quoting. Symbol#inspect returns `:p`,
           # which would inject a bare token into the JS source.
           selector_literal = selector.to_s.inspect
+          # XPath parse errors return [] silently to match Capybara's expected
+          # "not found" behavior (see FIND_WITHIN_JS comment above for why).
           js = if method == "xpath"
-                 "(typeof _lightpanda !== 'undefined') ? _lightpanda.xpathFind(#{selector_literal}, document) : []"
+                 <<~XPATH_FIND
+                   (function() {
+                     try {
+                       var r = document.evaluate(#{selector_literal}, document, null, 7, null);
+                       var nodes = [];
+                       for (var i = 0; i < r.snapshotLength; i++) nodes.push(r.snapshotItem(i));
+                       return nodes;
+                     } catch(e) { return []; }
+                   })()
+                 XPATH_FIND
                else
                  <<~CSS_FIND
                    (function() {
@@ -658,10 +790,27 @@ module Capybara
       end
 
       def find_in_frame(method, selector)
-        frame_node = @frame_stack.last
-        result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector,
-                                  return_by_value: false)
-        extract_node_object_ids(result)
+        refreshed = false
+        begin
+          with_default_context_wait do
+            frame_node = @frame_stack.last
+            result = call_function_on(frame_node.remote_object_id, FIND_IN_FRAME_JS, method, selector,
+                                      return_by_value: false)
+            extract_node_object_ids(result)
+          end
+        rescue NoExecutionContextError
+          # Issue #2400: a child iframe navigation re-emits executionContextCreated
+          # for the main-frame V8 context under the child's frameId, churning the
+          # iframe's executionContextId. Our stored remote_object_id is bound to
+          # the old contextId, so callFunctionOn raises "Cannot find context with
+          # specified id". with_default_context_wait can't help — the default
+          # context is fine; only the iframe handle is stale. Re-resolve the
+          # stack from locators captured at push_frame time and retry once.
+          raise if refreshed || !refresh_frame_stack!
+
+          refreshed = true
+          retry
+        end
       rescue JavaScriptError => e
         raise_invalid_selector(e, method, selector)
       end
@@ -674,6 +823,63 @@ module Capybara
         raise js_error
       end
 
+      # Snapshot iframe identifying attributes at push_frame time so we can
+      # re-find the element after lightpanda-io/browser#2400 churns its
+      # contextId. Returns a Hash on success or nil if the call fails — the
+      # latter blocks refresh attempts for this stack entry but leaves the
+      # original behaviour intact (caller falls through to the upstream
+      # error). Best-effort: never raises.
+      def capture_frame_locator(node)
+        call_function_on(node.remote_object_id, CAPTURE_FRAME_LOCATOR_JS)
+      rescue BrowserError
+        nil
+      end
+
+      # Re-resolve every level of @frame_stack from locators captured at
+      # push_frame time. Replaces stack entries in-place with FrameRef
+      # holders whose objectIds are bound to the current contextId.
+      # Returns true on success, false if any level can't be resolved
+      # (missing locator, iframe removed from DOM, fresh CDP error).
+      # Called from find_in_frame on NoExecutionContextError; failure is
+      # not fatal — the caller re-raises the original error.
+      def refresh_frame_stack!
+        return false if @frame_stack.empty?
+        return false if @frame_locators.any?(&:nil?)
+
+        fresh = []
+        @frame_locators.each_with_index do |locator, level|
+          node = level.zero? ? resolve_root_iframe(locator) : resolve_nested_iframe(fresh.last, locator)
+          return false unless node
+
+          fresh << node
+        end
+
+        @frame_stack.replace(fresh)
+        true
+      rescue BrowserError
+        false
+      end
+
+      def resolve_root_iframe(locator)
+        # Runtime.evaluate doesn't accept call arguments, so inline the
+        # locator as a JSON literal into the invocation expression. The
+        # locator was captured from the browser's own getAttribute reads
+        # at push_frame time, so JSON.generate is safe.
+        expression = "(#{RESOLVE_ROOT_IFRAME_JS})(#{locator.to_json})"
+        result = evaluate_with_ref(expression)
+        return nil unless result && result["objectId"]
+
+        FrameRef.new(result["objectId"])
+      end
+
+      def resolve_nested_iframe(parent, locator)
+        result = call_function_on(parent.remote_object_id, RESOLVE_NESTED_IFRAME_JS, locator,
+                                  return_by_value: false)
+        return nil unless result && result["objectId"]
+
+        FrameRef.new(result["objectId"])
+      end
+
       # Extract individual node objectIds from a remote array reference.
       def extract_node_object_ids(result)
         return [] unless result && result["objectId"]
@@ -981,6 +1187,21 @@ module Capybara
         await_navigation(&)
       end
 
+      # Step the session history by `offset` (-1 = back, +1 = forward) using
+      # native CDP. `Page.getNavigationHistory` returns the entry list and
+      # `currentIndex`; `Page.navigateToHistoryEntry` jumps to the chosen
+      # entry's `id`. No-op when the offset would step past either end so
+      # the behavior matches `history.back()` / `history.forward()` on a
+      # bounded session history.
+      def navigate_history(offset)
+        history = page_command("Page.getNavigationHistory")
+        target_index = history["currentIndex"] + offset
+        entries = history["entries"]
+        return if target_index.negative? || target_index >= entries.length
+
+        page_command("Page.navigateToHistoryEntry", entryId: entries[target_index]["id"])
+      end
+
       # Common navigation lifecycle shared by `wait_for_page_load` (fresh
       # `Page.navigate`) and `wait_for_navigation` (back / forward / reload).
       # Subscribes to Page.loadEventFired, runs the trigger, waits briefly for