capybara-lightpanda 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bb84252bec4e22492ad1e2165a63842c3fad60ab9d80ee0df60db55c2425c9a
-  data.tar.gz: '090fbdca94bf7e482dda301a2aad4b51065211972bff4a06a9aa3e848a2a9ef4'
+  metadata.gz: 8d8e1d17876b5bb6bc851b841e43c5abca5d3dc6d6b491acedfc571f0022de4a
+  data.tar.gz: 01f631fdae83149cf643d2bffb28ff5abf21dae55fea7afec0c40b06704eea61
 SHA512:
-  metadata.gz: 3bf39418c02c38ead4fc8ead897064730711d97bcd2e787d049ae1860e89bcf07e155f4ebb3743263e4c531250935d73e02ae768196aa5d27e205f8c3f903d1e
-  data.tar.gz: 145951b47b0ef2ce55e4c02932c006efdaa48fd6ac556daf5a18fef5949d63ebf861eabf262a93bb1a2a51dcc46b89d9d510fcbcc5c38fc7153dc1a0cd24402b
+  metadata.gz: 9479e55672546d80256ace5e39fb9bf3639d2fec1cd554e1977a0a627990036cced67fbfae8e3467388ac7b9140d82c74aac21a684c98da9e3e45e4aa688eb55
+  data.tar.gz: 93fd13d1409125462b7931db7cc2b249916c7a05465c656492b89dac0ef137824dcd4a682e3a6df91657d34f2e0f22502faef0e13c9b79b3ddedd171cec4f345

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.4.1] - 2026-05-19
+
+### Fixed
+
+- The gem now picks up a pre-installed `lightpanda` from `PATH` (e.g. `brew install lightpanda-io/lightpanda/lightpanda` or a manual `curl` install) instead of always re-downloading the nightly binary into `~/.cache/lightpanda/`. Test suites that block outbound HTTP via VCR/WebMock no longer crash on the surprise GET to `github.com` the first time the driver starts. Auto-download still kicks in if no `lightpanda` is on `PATH` and the gem cache is empty/stale, so default setups are unaffected.
+
+## [0.4.0] - 2026-05-17
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6269 (published 2026-05-16 or later). The driver refuses to start against older binaries.
+
+### Added
+
+- `Driver#status_code` and `Driver#response_headers` — read the HTTP status code and response headers from the most recent document navigation. Lookups on `response_headers` are case-insensitive (`response_headers["Content-Type"]` works against any header casing). Caveat: calling `driver.network.disable` also disables the navigation-response handler — they share a CDP toggle.
+- `Driver#with_lightpanda_browser { |browser| … }` and `element.with_lightpanda_node { |node| … }` — escape hatches for tests that need raw access to Lightpanda's CDP client and `LP.*` extensions. Mixed-driver setups are safe: the element helper no-ops against non-Lightpanda elements.
+- Shifted-symbol keyboard input — `send_keys([:shift, "1"])` now produces `"!"`, `[:shift, "2"]` produces `"@"`, etc., matching a US keyboard layout. Letters fall through to their existing upcase path unchanged.
+- `LIGHTPANDA_EXTRA_ARGS` env var — whitespace-split tokens get appended to the spawned `lightpanda serve` command line, so you can experiment with opt-in upstream flags (e.g. `LIGHTPANDA_EXTRA_ARGS="--log_format pretty"`) without forking the gem.
+- `Binary.configure { |b| b.required_version = "…"; b.cache_time = …; b.install_dir = "…"; b.proxy_addr = … }`, plus `Binary.update`, `Binary.remove`, `Binary.current_version`, `Binary.install_path` — explicit, scriptable binary management. Pair with the new `rake lightpanda:binary:{version, update[version], remove}` tasks if you want to download the binary once before parallel workers start.
+
+### Changed
+
+- Inline `<style> @media` rules and `window.matchMedia(q).matches` now evaluate against the fixed 1920×1080 viewport, so visibility checks on mobile-vs-desktop CTAs gated by **inline** `@media` queries no longer surface both variants. External `<link rel="stylesheet">` responsive CSS is still out of scope (browser limitation — see README).
+- `network.headers = { … }`, `network.add_headers(…)`, and `network.clear_headers` now enable the Network domain on first call. No need to flip `network.enable` separately.
+
+### Fixed
+
+- A WebSocket-level error (bad frame, oversized message) no longer tears down the Ruby process. Pending CDP commands now fail immediately on disconnect instead of blocking for the full 30 s timeout, so teardown after a browser crash no longer freezes the suite.
+- `Cookies#load` now restores the `SameSite` attribute. Auth-cookie flows that rely on `SameSite=Strict` / `Lax` survive a YAML round-trip through `cookies.store` / `cookies.load`.
+- Stale (detached) element references now raise `ObsoleteNode` from every node operation, not just `text` / `all_text` / `visible_text`. Capybara's automatic-reload re-runs the original query instead of silently reading stale data.
+- A browser crash followed by reconnect now wipes session state (modal subscriptions, frame stack). Subsequent tests no longer see "no dialog fired" or stale iframe handles.
+- `save_screenshot` from Rails' `before_teardown` after a failed system test no longer masks the original failure with a "browser already gone" stack trace.
+- `find_modal` of the wrong type now reports the message of whatever other dialog actually fired — so an `alert` firing where the test expected a `confirm` shows up clearly in the failure message.
+- A `find(...)` immediately after a click that triggers navigation no longer raises `NoExecutionContextError`.
+- A broken or permission-denied `lsof` now surfaces as a `BinaryError` pointing at the underlying problem instead of silently failing port reclamation.
+- `session.scroll_to(node)` no longer raises `NotImplementedError`. Lightpanda still has no rendering so the call does nothing, but callers who didn't care about the result no longer crash.
+- `network.traffic` reads (used by `wait_for_network_idle`) are now thread-safe — no more inconsistent counts when the CDP message thread is busy.
+- Several internal browser-side handle leaks plugged — long shared-spec sessions no longer accumulate orphaned object references.
+
+### Removed
+
+- The last JavaScript polyfill bundle (form-IDL accessors like `form.enctype` and submitter `formAction` / `formMethod`) is gone — Lightpanda implements these natively now. No code change required on your end.
+- The iframe-context retry workaround and the `HTMLDialogElement.show` / `showModal` / `close` polyfill — both implemented natively upstream. No code change required.
+
+### Internal
+
+- `rake spec:shared:parallel` — the Capybara shared-spec battery now runs in parallel across N worker processes (~3.7× at 4 workers, ~6.6× at 8). Default worker count is `Etc.nprocessors / 2`; override with `RSPEC_WORKERS=N`.
+
 ## [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.

data/README.md

@@ -40,6 +40,9 @@ Capybara.javascript_driver = :lightpanda
 > [!TIP]
 > 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. By design it does **not** fetch external `<link rel="stylesheet">`, evaluate `@media` rules, or implement `window.matchMedia()`. Any spec whose visibility depends on responsive CSS — for example a mobile/desktop CTA pair hidden via `@media (min-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.
+
 ## Credits
 
 - [Lightpanda](https://lightpanda.io/) — the headless browser

data/lib/capybara/lightpanda/auto_scripts.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    module AutoScripts
+      JS_PATH = File.expand_path("javascripts/index.js", __dir__).freeze
+      JS = File.read(JS_PATH).freeze
+    end
+  end
+end

data/lib/capybara/lightpanda/binary.rb

@@ -23,7 +23,7 @@ module Capybara
         end
       end
 
-      GITHUB_RELEASE_URL = "https://github.com/lightpanda-io/browser/releases/download/nightly"
+      GITHUB_RELEASE_URL = "https://github.com/lightpanda-io/browser/releases/download"
 
       PLATFORMS = {
         %w[x86_64 linux] => "lightpanda-x86_64-linux",
@@ -31,23 +31,101 @@ module Capybara
         %w[arm64 darwin] => "lightpanda-aarch64-macos",
       }.freeze
 
+      DEFAULT_CACHE_TIME = 86_400
+
       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
+        # affects download URL construction — the gem's MINIMUM_NIGHTLY_BUILD
+        # floor is still enforced at process start.
+        attr_accessor :required_version
+
+        # Seconds before a cached unpinned binary is re-downloaded. Pinned
+        # binaries are never refreshed on age (they're pinned).
+        attr_writer :cache_time, :install_dir, :logger
+        attr_accessor :proxy_addr, :proxy_port, :proxy_user, :proxy_pass
+
+        def cache_time
+          @cache_time ||= Integer(ENV.fetch("LIGHTPANDA_CACHE_TIME", DEFAULT_CACHE_TIME))
+        end
+
+        def install_dir
+          @install_dir ||= File.dirname(default_binary_path)
+        end
+
+        def logger
+          return @logger if defined?(@logger) && @logger
+          return nil unless ENV["LIGHTPANDA_DEBUG"]
+
+          @logger = Capybara::Lightpanda::Logger.new($stderr.tap { |s| s.sync = true })
+        end
+
+        def configure
+          yield self
+        end
+
         def path
-          @path ||= find_or_download
+          @path ||= update
         end
 
-        def find_or_download
-          find || download
+        # Canonical entrypoint: ensure the binary at install_path is current,
+        # download if needed, return its path. Pinned (required_version set)
+        # never re-downloads when present. Unpinned re-downloads when older
+        # than cache_time. When unpinned and the gem cache is empty/stale,
+        # an already-installed `lightpanda` on PATH (e.g. via Homebrew) wins
+        # over re-downloading — keeps test suites running under VCR/WebMock
+        # from triggering surprise HTTP to github.com.
+        def update
+          destination = install_path
+
+          if required_version
+            if File.executable?(destination)
+              log("Pinned #{required_version} present at #{destination}")
+              return destination
+            end
+            return download
+          end
+
+          if cached_fresh?(destination)
+            log("Cached binary at #{destination} is fresh (< #{cache_time}s)")
+            return destination
+          end
+
+          if (system_path = system_binary_path)
+            log("Using lightpanda from PATH at #{system_path}")
+            return system_path
+          end
+
+          download
         end
 
-        # Always return the nightly binary, downloading if missing or stale.
-        # Skips PATH lookup so the system binary is never used.
-        def ensure_nightly(max_age: 86_400)
-          path = default_binary_path
-          download if !File.executable?(path) || (Time.now - File.mtime(path)) > max_age
+        # Delete the cached binary. Returns the path that was deleted, or nil
+        # if nothing was there.
+        def remove
+          path = install_path
+          unless File.exist?(path)
+            log("Nothing to remove at #{path}")
+            return nil
+          end
+
+          File.delete(path)
+          @path = nil
+          log("Removed #{path}")
           path
         end
 
+        # Returns the `lightpanda version` output of the cached binary, or nil
+        # if the binary isn't present / not runnable.
+        def current_version
+          path = install_path
+          return nil unless File.executable?(path)
+
+          stdout, _, status = Open3.capture3(path, "version")
+          status.success? ? stdout.strip : nil
+        rescue Errno::ENOENT
+          nil
+        end
+
         def run(*)
           stdout, stderr, status = Open3.capture3(path, *)
 
@@ -72,28 +150,18 @@ module Capybara
           result.output.strip
         end
 
-        def find
-          env_path = ENV.fetch("LIGHTPANDA_BIN", nil)
-          return env_path if env_path && File.executable?(env_path)
-
-          path_binary = find_in_path
-          return path_binary if path_binary
-
-          default_path = default_binary_path
-          return default_path if File.executable?(default_path)
-
-          nil
-        end
-
         def download
           binary_name = platform_binary
-          url = "#{GITHUB_RELEASE_URL}/#{binary_name}"
-          destination = default_binary_path
+          tag = required_version || "nightly"
+          url = "#{GITHUB_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)
+          @path = destination
 
           destination
         end
@@ -111,35 +179,37 @@ module Capybara
           File.join(cache_dir, "lightpanda", "lightpanda")
         end
 
-        private
-
-        def find_in_path
-          ENV["PATH"].to_s.split(File::PATH_SEPARATOR).each do |dir|
-            path = File.join(dir, "lightpanda")
-
-            return path if File.executable?(path) && native_binary?(path)
+        # Path the gem writes the downloaded binary to. Honors a
+        # user-configured install_dir; otherwise falls back to default_binary_path.
+        def install_path
+          if @install_dir
+            File.join(@install_dir, "lightpanda")
+          else
+            default_binary_path
           end
-
-          nil
         end
 
-        def native_binary?(path)
-          header = File.binread(path, 4)
+        private
 
-          return true if elf_binary?(header)
-          return true if mach_o_binary?(header)
+        # Scan ENV["PATH"] for an executable `lightpanda`. Returns the first
+        # match (PATH order), or nil. Lets `brew install lightpanda-io/
+        # lightpanda/lightpanda` (and Linux package installs at /usr/local/bin)
+        # short-circuit the auto-download path in `update`.
+        def system_binary_path
+          ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+            next if dir.empty?
 
-          false
-        rescue StandardError
-          false
+            candidate = File.join(dir, "lightpanda")
+            return candidate if File.file?(candidate) && File.executable?(candidate)
+          end
+          nil
         end
 
-        def elf_binary?(header)
-          header.start_with?("\x7FELF")
-        end
+        def cached_fresh?(path)
+          return false unless File.executable?(path)
+          return true if cache_time.zero?
 
-        def mach_o_binary?(header)
-          header.start_with?("\xCF\xFA\xED\xFE")
+          (Time.now - File.mtime(path)) < cache_time
         end
 
         def normalize_arch(arch)
@@ -167,7 +237,7 @@ module Capybara
         def follow_redirects(uri, destination, limit = 10)
           raise BinaryNotFoundError, "Too many redirects" if limit.zero?
 
-          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http_start(uri) do |http|
             request = Net::HTTP::Get.new(uri)
 
             http.request(request) do |response|
@@ -177,6 +247,7 @@ module Capybara
                   response.read_body { |chunk| file.write(chunk) }
                 end
               when Net::HTTPRedirection
+                log("Redirected → #{response['location']}")
                 follow_redirects(URI.parse(response["location"]), destination, limit - 1)
               else
                 raise BinaryNotFoundError, "Failed to download binary: #{response.code} #{response.message}"
@@ -184,6 +255,22 @@ module Capybara
             end
           end
         end
+
+        def http_start(uri, &)
+          if proxy_addr
+            Net::HTTP.start(
+              uri.host, uri.port,
+              proxy_addr, proxy_port, proxy_user, proxy_pass,
+              use_ssl: uri.scheme == "https", &
+            )
+          else
+            Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", &)
+          end
+        end
+
+        def log(message)
+          logger&.puts("[lightpanda binary] #{message}")
+        end
       end
     end
   end