capybara-lightpanda 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7ec772a2b4254837394ec6705d94c8759e750f0f2ba7ce12ac4d02bfdd30bf5
-  data.tar.gz: a65953b578a45f0f652f0f3dadc2334bfa6db4ae6c6f4d931da4d9730f3656a1
+  metadata.gz: 11c82a5cc9cde03ae1a231efb72764a35c77beda531118960fb499c209348a3e
+  data.tar.gz: 66f4b3190f2dcc158925fd26e7b7b0590a8460d9789737d8bb08c3d5f9deed6b
 SHA512:
-  metadata.gz: 95af3574b27e16d24845f3bcdacc78779c8a036a81d7ab68870de8fd8bc957b8557a2beb9812f85030e7e1e74d994abf2f0d43e116ebb3c87069c52006012429
-  data.tar.gz: 20bf49585073a9d06e76da5460aeb143d653de2dab9a7d1a11d55b16603e9d956737147d712403416f3a8818967193e3150ebc7ae04dbf248ab52b3c62a40495
+  metadata.gz: 1dc37a8e9df8fb0533718e9aa17f35cb7dc162251a0f5f46e036b054afcbeec2da928277ac3af60ac592493d80357913f1f8d2384d671baa2e802905b6357c09
+  data.tar.gz: 95c360b046406da232e6104fe9cb10aa158fedc2ff4e3cdeaa7c12042bc3bd725d9825bd8e2c730365e46c0f9f884c02c4a523af1ce9e4d582fc5aa760093e99

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [0.10.0] - 2026-08-19
+
+> **Update Lightpanda before upgrading.** This release requires a Lightpanda nightly build ≥ 8448 **or a tagged release ≥ 0.3.7**. The driver refuses to start below either floor and tells you which version it found. If you pin the browser (see below), pin `0.3.7` or newer.
+
+### Added
+
+- **Tagged Lightpanda releases are accepted, and can be pinned.** Set `Capybara::Lightpanda::Binary.required_version = "0.3.7"` and the driver downloads that exact release, so CI runs against the same browser every time instead of whatever the rolling nightly is that morning. Pinned binaries live in their own path (`~/.cache/lightpanda/lightpanda-0.3.7`), so several can coexist and a stale nightly can no longer shadow the pin. The docs have a CI recipe, including the pre-provisioning step suites that stub HTTP (VCR/WebMock) need.
+- **File downloads.** When your app sends a file with `Content-Disposition: attachment` (`send_file`, `send_data`), the browser saves it to disk. `page.driver.downloads` lists the completed files, `page.driver.wait_for_download` blocks until in-flight ones finish. Turned on automatically when a destination exists: the new `:save_path` driver option, else `Capybara.save_path`. Responses that rely on MIME type alone (a bare `text/csv` with no `Content-Disposition`) are rendered as a page, not downloaded.
+- **Uncaught JavaScript errors are captured.** `page.driver.browser.page_errors` returns every uncaught exception and unhandled promise rejection from page JS (message, file, line, column, stack). Previously a handler dying on a `TypeError` left `console_logs` empty and the failure surfaced far away as `ElementNotFound`. Kept separate from `console_logs`, which still holds only explicit `console.*` calls.
+- **`raise_on_unhandled_modal` driver option.** A `confirm`/`prompt`/`alert` that opens outside an `accept_*`/`dismiss_*` block used to be silently cancelled by the browser, so a runaway confirm cancelled the action and the spec still passed. The driver now warns on stderr naming the dialog text; with `raise_on_unhandled_modal: true` it raises `Capybara::Lightpanda::UnhandledModalError` from the click or `visit` that opened it. Wrapped dialogs are unaffected.
+- **Window API.** `page.current_window.resize_to(w, h)`, `.size`, `.maximize`, `current_window_handle`/`window_handles`, `switch_to_window` — all single-window (Lightpanda has one page per connection; `open_new_window` says so). One sharp edge: resizing changes `window.innerWidth` and `matchMedia` immediately but does not re-evaluate `@media` for the page already loaded, so **resize, then `visit`** for responsive specs.
+- **The `:window_size` driver option now does something.** It sets the viewport that `window.innerWidth`/`innerHeight`, `matchMedia` and `@media` rules see, so `@media`-gated markup resolves at the size you ask for. Nothing reflows (there is no layout engine), so an element off-viewport is not reported as obscured.
+- **Selenium-named helpers shared across Rails suites work.** `page.driver.browser.logs.get(:browser)` (the "no JS errors" helper), `browser.execute_async_script` (axe-core), `element.native.send_keys(...)`, and `browser.execute_cdp` for raw protocol calls. `browser.switch_to.alert` raises with a message pointing at `accept_confirm`/`accept_alert` — dialogs here are answered before they open, so there is nothing to switch to afterwards.
+- `Node#path` returns an XPath that re-finds the element (Capybara's contract), and `"(: Shadow DOM element - no XPath :)"` for an element inside a shadow root, as Selenium does. `Node#exists?` answers whether a node is still attached without raising.
+- **Intel Macs and arm64 Linux** (Graviton-class CI runners) are supported; Lightpanda publishes binaries for both, the gem just refused to look them up.
+
+### Changed
+
+- **Minimum Lightpanda version raised** (nightly 8448 / release 0.3.7). What that buys your suite: elements hidden by Tailwind v4's layered CSS are correctly invisible; `<form method="dialog">` closes its dialog (the Turbo-confirm pattern in Spree 5's admin) instead of navigating away; `select` reaches options inside `<optgroup>`; pages scheduling more than 512 timers no longer stall; dynamically inserted scripts load and fire `load`/`error` correctly; setting a `<select>` value can no longer crash the browser mid-spec; and non-ASCII download filenames come through intact.
+- **`Element#drop` hands files to the browser** instead of streaming their bytes through the driver, so there is no longer a size ceiling on dropped files and `file.type` is what the browser sniffs. Same call, same behavior for the page. Capybara's own `Element#drop` shared specs now run against the driver.
+- **Visible text is what the browser renders.** `text` uses the browser's own `innerText`, so block breaks, hidden descendants and whitespace match what a real browser reports, instead of the driver's approximation.
+- **Clicking a wrapper element reaches the widget inside it.** A click on a plain container descends to the first interactive child a pointer would have hit, so select2 dropdowns (and similar widgets that bind on an inner node) open when a helper clicks the outer container.
+- **`hover` fires `mouseenter` as well as `mouseover`**, so Stimulus `mouseenter->` actions, Floating UI and tippy menus open. CSS `:hover` rules still do not apply (no pointer state).
+- Default `window_size` is `[1920, 1080]`, Lightpanda's own default, rather than `[1024, 768]`; suites that want the old size pass it explicitly. An invalid `window_size` raises `ArgumentError` at driver construction.
+- Large `execute_script` payloads (axe-core-sized bundles and bigger) no longer drop the connection: the CDP message cap is 100 MiB.
+- More of Capybara's shared specs run and pass, and stay as regression cover: shadow DOM (`#shadow_root` finding/clicking/text), `node #style`/`#matches_style?`, `send_keys` key events, and `fetch`/XHR `FormData` submissions.
+
+### Fixed
+
+- **A redirect no longer stalls `wait_for_network_idle` for the rest of the session.** After any `redirect_to` (post-create, post-login), `page.driver.network.pending_connections` stayed at 1 and every `wait_for_network_idle` burned its full timeout. Redirect chains are tracked correctly now, `network.traffic` shows the 302 and the final 200 on the right URLs, and `status_code` still reports the final page. Regular clicks and visits were never affected.
+- **A pinned browser version was silently ignored** whenever a binary was already cached, so CI kept running the nightly the pin was meant to replace. Pins are now self-verifying (see Added).
+- **An interrupted browser download no longer corrupts the cached binary.** The refresh wrote over the file in place, so a dropped connection left a zero-byte "executable" that the fallback path then handed back as usable. Downloads go to a temp file and are renamed into place atomically.
+
+### Internal
+
+- Docs site resynced with what the gem does; a local `script/real-app` harness boots the real-apps CI targets and captures `console_logs`/`network.traffic` per failing example.
+
 ## [0.9.0] - 2026-06-18
 
 ### Fixed

data/README.md

@@ -20,6 +20,16 @@ Self-contained — built-in CDP client, no external browser-client gem required.
 
 </div>
 
+## Requirements
+
+| | |
+|---|---|
+| **Ruby** | ≥ 3.3 — CI covers 3.3 and 4.0 |
+| **Capybara** | ≥ 3.0, < 5 |
+| **Platforms** | Linux `x86_64` · Linux `aarch64` · macOS Apple Silicon · macOS Intel · Windows through WSL2 (no native Windows build upstream) |
+
+An unsupported host raises `UnsupportedPlatformError` at boot, naming what it detected — it never fails halfway through a suite.
+
 ## Install
 
 Add this to your `Gemfile` and run `bundle install`:
@@ -44,7 +54,10 @@ driven_by :lightpanda
 > The Lightpanda binary is auto-downloaded on first use — no separate install step needed.
 
 > [!IMPORTANT]
-> Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), but `@media` rules and `window.matchMedia()` evaluate against a fixed 1920×1080 viewport — there is no resize emulation. Any spec whose visibility depends on a non-desktop viewport — for example a mobile-only CTA shown via `@media (max-width: …)` — should stay on Cuprite (or whichever full-browser driver you were already using). The [dual-driver setup](https://navidemad.github.io/capybara-lightpanda/#docs) routes the layout-sensitive minority to Cuprite and the structural majority to Lightpanda for speed.
+> Lightpanda is a headless agentic browser, not a layout engine. External `<link rel="stylesheet">` **are** fetched and applied (the gem enables this by default), and `@media` / `window.matchMedia()` evaluate against the `window_size` you configure — so a mobile-only CTA gated by `@media (max-width: …)` resolves at the width you ask for. What's missing is *layout*: nothing reflows, `getBoundingClientRect` stays synthetic, and there is no real scroll. Specs that assert on pixel geometry, scrolling, or screenshots — plus the two that catch people out, a second browser tab and a menu revealed purely by CSS `:hover` — should stay on Cuprite (or whichever full-browser driver you were already using). The [per-spec dual-driver setup](https://navidemad.github.io/capybara-lightpanda/docs/#dual-per-spec) routes that minority to Cuprite and the structural majority to Lightpanda for speed.
+
+> [!TIP]
+> For reproducible CI, pin the browser: `Capybara::Lightpanda::Binary.required_version = "0.3.7"`. Without a pin the driver tracks Lightpanda's rolling `nightly` tag, which moves under you. See [Pinning the browser version](https://navidemad.github.io/capybara-lightpanda/docs/#pinning).
 
 ## Credits
 

data/lib/capybara/lightpanda/auto_scripts.rb

@@ -17,7 +17,9 @@ module Capybara
 
       # Order matters: declarations (turbo, predicates) before the wiring
       # (attach) that reads their names. banner is a leading comment block.
-      PARTS = %w[banner.js turbo.js predicates.js attach.js].freeze
+      # turbo.js and errors.js register their listeners at top level and expose
+      # nothing through attach.js, so they only need to run inside the IIFE.
+      PARTS = %w[banner.js turbo.js errors.js predicates.js attach.js].freeze
 
       # The guard short-circuits a repeat run before turbo.js can register its
       # listeners a second time (double-registration would double-count

data/lib/capybara/lightpanda/binary.rb

@@ -11,8 +11,19 @@ module Capybara
     class Binary
       GITHUB_RELEASE_URL = "https://github.com/lightpanda-io/browser/releases/download"
 
+      # Upstream publishes all four arch/OS combinations on every channel —
+      # verified 2026-07-26 against the `nightly` tag and release 0.3.6 (the
+      # MINIMUM_RELEASE floor, so any acceptable pin carries them too). Intel
+      # macOS and arm64 Linux were absent here and raised
+      # UnsupportedPlatformError on machines upstream ships a binary for: Intel
+      # MacBooks, and Graviton / arm64 CI runners. normalize_arch folds arm64 ->
+      # aarch64, so the arm64 rows are unreachable defensive duplicates kept for
+      # symmetry with the pre-existing arm64-darwin one.
       PLATFORMS = {
         %w[x86_64 linux] => "lightpanda-x86_64-linux",
+        %w[aarch64 linux] => "lightpanda-aarch64-linux",
+        %w[arm64 linux] => "lightpanda-aarch64-linux",
+        %w[x86_64 darwin] => "lightpanda-x86_64-macos",
         %w[aarch64 darwin] => "lightpanda-aarch64-macos",
         %w[arm64 darwin] => "lightpanda-aarch64-macos",
       }.freeze
@@ -143,17 +154,45 @@ module Capybara
           nil
         end
 
+        # Downloads into a sibling temp file and renames it into place only
+        # once the transfer finished.
+        #
+        # Writing straight to `destination` corrupted a working binary on any
+        # interrupted transfer: File.open(_, "wb") truncates the existing file
+        # the moment the request starts, and truncation KEEPS the mode bits —
+        # so a dropped connection left a partial file that still answered
+        # File.executable? => true. #update's "fall back to the cached binary"
+        # rescue then handed that corpse back as if it were the usable stale
+        # binary, warning as though nothing was wrong. That is the common path,
+        # not an edge case: past cache_time, #update calls #download precisely
+        # when a good binary is already sitting at `destination`.
+        #
+        # rename(2) within one directory is atomic, so a concurrent reader sees
+        # either the old binary or the new one, never a half-written one. The
+        # temp file is a sibling (not Dir.tmpdir) so the rename never crosses a
+        # filesystem, and chmod happens before it so the binary is never
+        # visible non-executable. Two racing downloads get distinct temp names
+        # and both rename a complete file — last writer wins, both are valid.
         def download
           binary_name = platform_binary
           tag = required_version || "nightly"
-          url = "#{GITHUB_RELEASE_URL}/#{tag}/#{binary_name}"
+          url = "#{release_url}/#{tag}/#{binary_name}"
           destination = install_path
 
           log("Downloading #{binary_name} (#{tag}) → #{destination}")
           FileUtils.mkdir_p(File.dirname(destination))
 
-          download_file(url, destination)
-          FileUtils.chmod(0o755, destination)
+          # ::Process, not Process — Capybara::Lightpanda::Process would win.
+          temp = "#{destination}.download-#{::Process.pid}"
+          begin
+            download_file(url, temp)
+            FileUtils.chmod(0o755, temp)
+            File.rename(temp, destination)
+          ensure
+            # No-op on success (rename consumed it). ensure, not rescue, so an
+            # Interrupt mid-download cleans up too; rm_f ignores a missing file.
+            FileUtils.rm_f(temp)
+          end
 
           destination
         end
@@ -174,12 +213,20 @@ module Capybara
         #   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.
+        # - Path equals our cache AND a pin is set → the version is a deliberate
+        #   choice, so tell the user to raise the pin. The re-provision one-liner
+        #   would be a dead end here: it re-downloads the same pinned release and
+        #   lands on the identical "too old" error.
         # - Anything else (user-managed install at a custom path) → keep
         #   the curl-overwrite suggestion, since we don't know how the file
         #   got there.
         def update_hint(binary_path)
           if brew_managed?(binary_path)
             "brew update && brew upgrade lightpanda"
+          elsif binary_path == install_path && required_version
+            "Capybara::Lightpanda::Binary.required_version is pinned to " \
+              "#{required_version} — raise the pin to a newer release, " \
+              "or unset it to track the rolling nightly."
           elsif binary_path == install_path
             PROVISION_HINT
           else
@@ -203,16 +250,31 @@ module Capybara
 
         # Path the gem writes the downloaded binary to. Honors a
         # user-configured install_dir; otherwise falls back to default_binary_path.
+        #
+        # A pin gets its own filename (`lightpanda-0.3.5`) rather than sharing
+        # the rolling-nightly one. `update` only checks that a file EXISTS at
+        # this path, not which version it holds, so on a shared path a nightly
+        # left over from an earlier run would be accepted as "the pin" — setting
+        # required_version on any machine with a warm cache (every CI runner
+        # restoring a cache, every existing dev checkout) would silently keep
+        # running the nightly it was meant to replace. Version-scoping makes the
+        # pin self-verifying and lets several pins coexist in one cache dir.
         def install_path
-          if @install_dir
-            File.join(@install_dir, "lightpanda")
-          else
-            default_binary_path
-          end
+          dir = @install_dir || File.dirname(default_binary_path)
+          basename = required_version ? "lightpanda-#{required_version}" : "lightpanda"
+
+          File.join(dir, basename)
         end
 
         private
 
+        # Release host, as its own method so tests can point #download at a
+        # local socket and exercise the real streaming writer (which is where
+        # the truncation bug lived) instead of stubbing it out.
+        def release_url
+          GITHUB_RELEASE_URL
+        end
+
         # Detects a Homebrew-managed binary by checking whether `path` is a
         # symlink that resolves into a `/Cellar/` directory — the convention
         # both `/opt/homebrew` (Apple Silicon) and `/usr/local` (Intel /

data/lib/capybara/lightpanda/browser/console.rb

@@ -23,6 +23,34 @@ module Capybara
           @console_logs_mutex.synchronize { @console_logs.clear }
         end
 
+        # Uncaught page exceptions and unhandled promise rejections since the
+        # last `reset`: `{kind:, message:, url:, line:, column:, stack:,
+        # timestamp:}`, where `kind` is "error" or "unhandledrejection".
+        #
+        # Deliberately NOT folded into #console_logs. Chrome reports an
+        # uncaught exception through Runtime.exceptionThrown rather than
+        # consoleAPICalled, and Playwright/Puppeteer expose it as `pageerror`
+        # separately from `console` — so a suite that greps console_logs for
+        # errors on those stacks doesn't see exceptions there either. Merging
+        # them would also start failing every suite that already asserts
+        # console_logs holds no errors.
+        #
+        # Lightpanda emits no Runtime.exceptionThrown at all, so the source is
+        # a passive listener pair in javascripts/errors.js reporting over the
+        # console.debug sentinel channel. It sees what reaches `window`:
+        # exceptions a framework catches itself (Stimulus's handleError, any
+        # try/catch) never arrive, and a cross-origin script collapses to
+        # "Script error." with no detail. Partial by construction — but the
+        # alternative is the zero visibility that made the solidus taxon-tree
+        # failure take a hand-injected listener to explain.
+        def page_errors
+          @page_errors_mutex.synchronize { @page_errors.dup }
+        end
+
+        def clear_page_errors
+          @page_errors_mutex.synchronize { @page_errors.clear }
+        end
+
         private
 
         def subscribe_to_console_logs
@@ -32,7 +60,7 @@ module Capybara
           on("Runtime.consoleAPICalled") do |params|
             params["args"]&.each do |r|
               value = r["value"]
-              next if turbo_sentinel?(value)
+              next if driver_sentinel?(value)
 
               logger.puts(value)
             end
@@ -42,6 +70,9 @@ module Capybara
         TURBO_SENTINEL_PREFIX = "__lightpanda_turbo_"
         private_constant :TURBO_SENTINEL_PREFIX
 
+        PAGE_ERROR_SENTINEL_PREFIX = "__lightpanda_page_error_"
+        private_constant :PAGE_ERROR_SENTINEL_PREFIX
+
         # The Turbo activity tracker signals busy/idle via console.debug
         # sentinels (see subscribe_to_turbo_signals); every consoleAPICalled
         # consumer must filter them out of user-facing output.
@@ -49,14 +80,28 @@ module Capybara
           value.is_a?(String) && value.start_with?(TURBO_SENTINEL_PREFIX)
         end
 
+        # javascripts/errors.js reports uncaught page errors over the same
+        # console.debug channel, prefix + JSON payload.
+        def page_error_sentinel?(value)
+          value.is_a?(String) && value.start_with?(PAGE_ERROR_SENTINEL_PREFIX)
+        end
+
+        # Anything the injected bundle emits for the driver's own benefit. Every
+        # consoleAPICalled consumer filters on this, not on one prefix — missing
+        # a sentinel here leaks driver plumbing into user-facing output.
+        def driver_sentinel?(value)
+          turbo_sentinel?(value) || page_error_sentinel?(value)
+        end
+
         # 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.
+        # so capture works without any logger configured. Driver sentinels are
+        # plumbing, not page output: the Turbo ones are dropped, and the
+        # page-error ones are rerouted to @page_errors instead.
         def subscribe_to_console_capture
           on("Runtime.consoleAPICalled") do |params|
             args = params["args"]
@@ -65,16 +110,53 @@ module Capybara
             first = args.first&.dig("value")
             next if turbo_sentinel?(first)
 
+            if page_error_sentinel?(first)
+              record_page_error(first, params["timestamp"])
+              next
+            end
+
             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
+            push_capped(@console_logs, @console_logs_mutex, entry, CONSOLE_LOGS_LIMIT)
+          end
+        end
+
+        # Same cap and reasoning as CONSOLE_LOGS_LIMIT: a page erroring inside a
+        # loop (a rejected fetch on an interval) must not grow this unbounded.
+        PAGE_ERRORS_LIMIT = 1_000
+
+        # Parse one `__lightpanda_page_error_<json>` sentinel into @page_errors.
+        # A payload that won't parse is still worth surfacing — dropping it would
+        # turn "the page threw" into silence, which is the whole failure mode
+        # this exists to end — so it lands with the raw text as the message.
+        def record_page_error(sentinel, timestamp)
+          json = sentinel.delete_prefix(PAGE_ERROR_SENTINEL_PREFIX)
+          fields = begin
+            JSON.parse(json)
+          rescue JSON::ParserError
+            { "kind" => "error", "message" => json }
+          end
+
+          entry = {
+            kind: fields["kind"] || "error",
+            message: fields["message"].to_s,
+            url: fields["url"].to_s,
+            line: fields["line"],
+            column: fields["column"],
+            stack: fields["stack"],
+            timestamp: timestamp,
+          }
+          push_capped(@page_errors, @page_errors_mutex, entry, PAGE_ERRORS_LIMIT)
+        end
+
+        def push_capped(buffer, mutex, entry, limit)
+          mutex.synchronize do
+            buffer << entry
+            buffer.shift(buffer.size - limit) if buffer.size > limit
           end
         end
 

data/lib/capybara/lightpanda/browser/modals.rb

@@ -24,7 +24,19 @@ module Capybara
 
           on("Page.javascriptDialogOpening") do |params|
             entry = { type: params["type"], message: params["message"] }
-            @modal_messages_mutex.synchronize { @modal_messages << entry }
+            @modal_messages_mutex.synchronize do
+              @modal_messages << entry
+              # The pre-arm slot is single-shot on both sides: Lightpanda
+              # consumes its stashed response on this dialog, so we consume
+              # ours. No pre-arm in flight means Lightpanda just applied its
+              # silent default — remember it for the main thread; raising here
+              # would only die inside the subscriber.
+              if @modal_armed
+                @modal_armed = false
+              else
+                @unhandled_modal ||= entry
+              end
+            end
           end
 
           @modal_handler_installed = true
@@ -34,12 +46,31 @@ module Capybara
           prepare_modals
           params = { accept: true }
           params[:promptText] = text if text
-          page_command("LP.handleJavaScriptDialog", **params)
+          arm_modal { page_command("LP.handleJavaScriptDialog", **params) }
         end
 
         def dismiss_modal(_type)
           prepare_modals
-          page_command("LP.handleJavaScriptDialog", accept: false)
+          arm_modal { page_command("LP.handleJavaScriptDialog", accept: false) }
+        end
+
+        # Surface a dialog that opened with no pre-arm. Called from the main
+        # thread after every action that can open one (Browser#wait_for_idle,
+        # #go_to). Warns by default; raises when the driver was built with
+        # `raise_on_unhandled_modal: true` (Cuprite's option name). Either way
+        # the dialog is already gone — Lightpanda's default resolved it.
+        def check_unhandled_modal!
+          entry = @modal_messages_mutex.synchronize do
+            e = @unhandled_modal
+            @unhandled_modal = nil
+            e
+          end
+          return unless entry
+
+          message = unhandled_modal_message(entry)
+          raise UnhandledModalError, message if @options.raise_on_unhandled_modal
+
+          warn "[capybara-lightpanda] #{message}"
         end
 
         # `type` is accepted for the error message only: like Selenium (where
@@ -66,6 +97,26 @@ module Capybara
 
         private
 
+        def arm_modal
+          @modal_messages_mutex.synchronize { @modal_armed = true }
+          yield
+        end
+
+        LIGHTPANDA_DIALOG_DEFAULTS = {
+          "confirm" => "cancelled it",
+          "prompt" => "answered null",
+          "beforeunload" => "cancelled it",
+        }.freeze
+        private_constant :LIGHTPANDA_DIALOG_DEFAULTS
+
+        def unhandled_modal_message(entry)
+          with_text = entry[:message] ? " with text `#{entry[:message]}`" : ""
+          default = LIGHTPANDA_DIALOG_DEFAULTS.fetch(entry[:type].to_s, "dismissed it")
+          "A #{entry[:type]} dialog#{with_text} opened, but the action was not wrapped in " \
+            "accept_alert / accept_confirm / dismiss_confirm / accept_prompt / dismiss_prompt " \
+            "— Lightpanda #{default} by default"
+        end
+
         # 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.

data/lib/capybara/lightpanda/browser/navigation.rb

@@ -29,6 +29,7 @@ module Capybara
           else
             page_command("Page.navigate", url: url)
           end
+          check_unhandled_modal!
         end
         alias goto go_to
 

data/lib/capybara/lightpanda/browser/selenium_compat.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Browser
+      # Selenium-shaped entry points onto capability the gem already has under
+      # its own names.
+      #
+      # Rails suites reach through `page.driver.browser.<x>` in *shared* helpers
+      # — `expect_no_js_errors` (the widely-copied "catch JavaScript errors in
+      # your system tests" helper) calls `browser.logs.get(:browser)`, and the
+      # axe-core accessibility matchers call `browser.execute_async_script`.
+      # Both are driver-agnostic in intent but Selenium-named in fact, so on
+      # this driver they raised NoMethodError — which takes out every example in
+      # the file before a single real assertion runs. Two aliases buy back whole
+      # spec files (decidim's `account_spec.rb` + the shared "accessible page"
+      # examples, real-apps run 30116365373).
+      #
+      # Scope is deliberately narrow: alias what maps cleanly onto an existing
+      # API, and raise something *actionable* where the underlying model
+      # genuinely differs (see #switch_to). We do not grow a Selenium
+      # emulation layer.
+      module SeleniumCompat
+        # Selenium's `Logs#get(:browser)` shape over Browser#console_logs.
+        # `level` is the Selenium severity string ("SEVERE"/"WARNING"/…), not
+        # the CDP console type, because that is what callers compare against.
+        LogEntry = Struct.new(:level, :message, :timestamp) do
+          def to_s
+            "#{timestamp} #{level} #{message}"
+          end
+        end
+
+        # CDP `Runtime.consoleAPICalled` type -> Selenium log level. Anything
+        # unlisted (log, info, dir, table, …) is INFO, matching Chrome. "warn"
+        # is mapped alongside "warning" because Lightpanda emitted the former
+        # before upstream #2731.
+        CONSOLE_LEVELS = {
+          "error" => "SEVERE",
+          "assert" => "SEVERE",
+          "warning" => "WARNING",
+          "warn" => "WARNING",
+          "debug" => "DEBUG",
+          "trace" => "DEBUG",
+        }.freeze
+
+        # Selenium's `driver.logs` accessor. Only the `:browser` type has a
+        # meaning here; other Selenium log types (`:driver`, `:client`,
+        # `:server`) have no analogue and read as empty rather than raising, so
+        # a helper that probes several types still works.
+        class Logs
+          def initialize(browser)
+            @browser = browser
+          end
+
+          def get(type = :browser)
+            return [] unless type.to_sym == :browser
+
+            @browser.console_logs.map do |entry|
+              LogEntry.new(
+                CONSOLE_LEVELS.fetch(entry[:type], "INFO"),
+                entry[:text],
+                entry[:timestamp]
+              )
+            end
+          end
+
+          def available_types
+            [:browser]
+          end
+        end
+
+        # NOTE: unlike Chrome's `getLog`, this does NOT drain the buffer —
+        # repeated calls re-report the same entries. Draining would let an
+        # earlier reader silently swallow a JS error from a later assertion,
+        # and the buffer is already scoped to the session (cleared by
+        # Driver#reset!). Use #clear_console_logs for an explicit reset.
+        #
+        # Not memoized on purpose: Logs holds nothing but a back-reference, and
+        # an ivar here would have to be declared in Browser#initialize per the
+        # "all ivars initialized in the constructor" rule for these modules.
+        def logs
+          Logs.new(self)
+        end
+
+        # Selenium's `execute_async_script`: the script receives a completion
+        # callback as its last argument. Same contract as
+        # Driver#evaluate_async_script, minus the DOM-node unwrapping — callers
+        # on this path (axe-core et al.) hand back plain JSON.
+        def execute_async_script(script, *)
+          evaluate_async(script.to_s.strip, *)
+        end
+
+        # Selenium's raw-CDP escape hatch, as used by
+        # `page.driver.browser.execute_cdp("Network.setBlockedURLs", urls: [...])`.
+        # Scoped to the page session, matching Selenium — that covers the
+        # Page / Runtime / DOM / Network / Emulation domains a suite would
+        # reach for. Browser-scoped commands (Target.*, Browser.*) still go
+        # through Browser#command.
+        #
+        # Deliberately unvalidated: the point is to reach CDP surface the gem
+        # has not wrapped yet, so an unknown method should fail with
+        # Lightpanda's own error rather than one of ours.
+        def execute_cdp(method, **params)
+          page_command(method.to_s, **params)
+        end
+
+        # Selenium's post-hoc `switch_to.alert` cannot be honored: Lightpanda
+        # requires the accept/dismiss response to be armed BEFORE the action
+        # that opens the dialog (LP.handleJavaScriptDialog, upstream #2261 —
+        # Page.handleJavaScriptDialog deliberately errors), so by the time a
+        # caller could ask for the alert there is nothing left to answer. Fake
+        # it and the dialog silently keeps whatever default it already took.
+        # Raise with the migration instead of NoMethodError.
+        def switch_to
+          raise ::Capybara::NotSupportedByDriverError,
+                "Lightpanda arms dialog responses before the triggering action, so Selenium's " \
+                "post-hoc switch_to.alert has nothing to act on. Wrap the action instead: " \
+                "accept_alert/accept_confirm/accept_prompt (or Driver#accept_modal/#dismiss_modal), " \
+                "which pre-arm the response and still expose the dialog text."
+        end
+      end
+    end
+  end
+end