capybara-lightpanda 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d8e1d17876b5bb6bc851b841e43c5abca5d3dc6d6b491acedfc571f0022de4a
-  data.tar.gz: 01f631fdae83149cf643d2bffb28ff5abf21dae55fea7afec0c40b06704eea61
+  metadata.gz: 9d2922897678cf6ea18bd630b63703ae59ca213b4909e5c42d60e5c1b55e7faa
+  data.tar.gz: 8b01db5b4f0b7c8da5e13d2c9b157c2184463e3b22637ec1d6d5d4d3d84d17f7
 SHA512:
-  metadata.gz: 9479e55672546d80256ace5e39fb9bf3639d2fec1cd554e1977a0a627990036cced67fbfae8e3467388ac7b9140d82c74aac21a684c98da9e3e45e4aa688eb55
-  data.tar.gz: 93fd13d1409125462b7931db7cc2b249916c7a05465c656492b89dac0ef137824dcd4a682e3a6df91657d34f2e0f22502faef0e13c9b79b3ddedd171cec4f345
+  metadata.gz: 7e09df8530d946074c1b9022820ebe3ff6c3bc19d69ee1f543df7c3e65c6d6cc2ace6c65910028fb69ca7253488a88df10f3c271bcced82358e71e44c128cb1e
+  data.tar.gz: 93feae0c267585dfc745d01ec65d651b682903794588ea2cc18c3c071b313c4b869bde6c35cd8bfbe8c2e00b1c51ac49ba1cd6ddc5b624c33f1f0e7dc8575286

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.5.0] - 2026-05-22
+
+> **Update Lightpanda before upgrading.** Requires a nightly build ≥ 6353 (published 2026-05-21). The driver refuses to start against older binaries.
+
+### Changed
+
+- External `<link rel="stylesheet">` CSS is now fetched and applied by default. Responsive variants gated by an external stylesheet — a desktop-vs-mobile CTA defined in your app's compiled CSS bundle, say — now resolve to the single variant matching the fixed 1920×1080 viewport, so finding or clicking them no longer raises `Capybara::Ambiguous`. Specs that previously had to fall back to cuprite or Selenium for externally-loaded responsive CSS now run on lightpanda. The cost is one extra synchronous CSS fetch per `<link>` while the page loads.
+
+### Fixed
+
+- Suites no longer hang at exit. After the last test, the browser process could absorb the shutdown signal and keep the run blocked for minutes (much longer on CI) before being force-killed. The gem now closes the CDP connection before signaling the process and escalates to a hard kill if it doesn't exit promptly, so the process always dies fast and leaves no orphaned `lightpanda` behind.
+- Elements toggled via the `[hidden]` attribute now respect an explicit `display` set by your app's CSS, the way a real browser does. This clears the `Capybara::ElementNotFound` and visibility failures that hit dropdowns and disclosure widgets built with Stimulus or Alpine.
+- When your installed Lightpanda binary is too old, the update hint now matches where that binary actually lives — a `PATH` install, the gem's download cache, or a Homebrew install each get the right command instead of a generic one. Especially handy this release, since the raised floor means an outdated binary will refuse to start.
+
 ## [0.4.1] - 2026-05-19
 
 ### Fixed

data/lib/capybara/lightpanda/binary.rb

@@ -166,6 +166,30 @@ module Capybara
           destination
         end
 
+        # Build a path-appropriate "how to update" command for Process's
+        # too-old-binary error. Three branches:
+        #
+        # - Symlink into a `/Cellar/` directory → installed via Homebrew;
+        #   suggest `brew update && brew upgrade lightpanda` (brew pins
+        #   each user's binary at install time and doesn't refresh on its
+        #   own when the tap publishes a newer nightly).
+        # - Path equals our own cache → suggest the gem's rake tasks; the
+        #   `remove` step is required because `update` honors `cache_time`
+        #   and would otherwise no-op on a too-old-but-not-yet-expired file.
+        # - 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
+            "bundle exec rake lightpanda:binary:remove lightpanda:binary:update"
+          else
+            "curl -sL #{GITHUB_RELEASE_URL}/nightly/#{platform_binary} " \
+              "-o #{binary_path} && chmod +x #{binary_path}"
+          end
+        end
+
         def platform_binary
           arch = normalize_arch(RbConfig::CONFIG["host_cpu"])
           os = normalize_os(RbConfig::CONFIG["host_os"])
@@ -191,6 +215,19 @@ module Capybara
 
         private
 
+        # 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 /
+        # linuxbrew) use. Plain files (manual installs) and gem-cache files
+        # both return false.
+        def brew_managed?(path)
+          return false unless File.symlink?(path)
+
+          File.realpath(path).include?("/Cellar/")
+        rescue Errno::ENOENT, Errno::EACCES
+          false
+        end
+
         # 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)

data/lib/capybara/lightpanda/browser.rb

@@ -11,6 +11,49 @@ module Capybara
 
       delegate %i[on off] => :client
 
+      # --- Live-browser registry: clean teardown at process exit --------------
+      # Capybara's per-test reset (Driver#reset!) disposes only the
+      # BrowserContext and keeps the process + CDP connection alive, so a
+      # browser outlives the suite. With nothing calling #quit at exit, teardown
+      # would fall to the Process GC finalizer, which SIGTERMs the binary WITHOUT
+      # first closing the CDP WebSocket. Lightpanda swallows a *single* SIGTERM
+      # while a CDP connection is live (graceful shutdown blocks on the
+      # connection worker; it takes three signals to force-exit), so that SIGTERM
+      # is absorbed and only the STOP_GRACE_SECONDS SIGKILL escalation reaps it —
+      # 3s per process, and a hard hang before that escalation existed. #quit
+      # closes the WS first, so we track live browsers and #quit them from a
+      # single at_exit, guaranteeing the socket is closed before any SIGTERM.
+      @live = []
+      @live_mutex = Mutex.new
+      @at_exit_installed = false
+
+      class << self
+        def track(browser)
+          @live_mutex.synchronize do
+            @live << browser unless @live.include?(browser)
+            next if @at_exit_installed
+
+            @at_exit_installed = true
+            at_exit { quit_all }
+          end
+        end
+
+        def untrack(browser)
+          @live_mutex.synchronize { @live.delete(browser) }
+        end
+
+        # at_exit handler: close every live browser's CDP WebSocket (via #quit)
+        # before its Process finalizer can SIGTERM the binary. Per-browser rescue
+        # so one wedged browser can't strand the rest.
+        def quit_all
+          @live_mutex.synchronize { @live.dup }.each do |browser|
+            browser.quit
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
       # Lightpanda binary version (e.g. "lightpanda 0.2.9 nightly.5267") and
       # parsed nightly build number, captured at Process startup. nil when
       # the gem is connecting to an externally-managed Lightpanda via ws_url.
@@ -58,6 +101,7 @@ module Capybara
         create_page
 
         @started = true
+        self.class.track(self)
       end
 
       # Per-session BrowserContext (Chrome's incognito-profile primitive).
@@ -144,6 +188,7 @@ module Capybara
       end
 
       def quit
+        self.class.untrack(self)
         begin
           @client&.close
         rescue StandardError

data/lib/capybara/lightpanda/process.rb

@@ -8,6 +8,19 @@ module Capybara
       READY_PATTERN = /server running.*address\s*=\s*(\d+\.\d+\.\d+\.\d+:\d+)/m
       ADDRESS_IN_USE_PATTERN = /err=AddressInUse/
 
+      # Seconds to wait for a graceful SIGTERM before escalating to SIGKILL in
+      # `stop` / the GC finalizer. Lightpanda absorbs a *single* SIGTERM while a
+      # CDP connection is still live (graceful shutdown blocks on the connection
+      # worker — see .claude/rules/lightpanda-io.md limitation #7B). The PRIMARY
+      # fix is gem-side: Browser closes the CDP WebSocket before SIGTERM at exit
+      # (Browser.quit_all via at_exit), so SIGTERM lands after EOF and teardown is
+      # instant. This escalation is the BACKSTOP for crash / GC-abandon paths the
+      # at_exit can't reach — without it, a SIGTERM left to the finalizer (which
+      # can't close the WS) blocked Process.wait forever (the 45-min
+      # `rake test:all` hang). NOT the same as #2507/#2509 (telemetry curl-multi),
+      # which the gem never hits because it disables telemetry.
+      STOP_GRACE_SECONDS = 3
+
       # Floor for the cookie/navigation/redirect/modal/keyboard/css/forms/dispatch/
       # xpath/history/iframe-context/dialog fixes the gem now relies on:
       # PR #2255 (Network.clearBrowserCookies empty params + Network.getAllCookies),
@@ -49,13 +62,23 @@ module Capybara
       # hardcoded 1920×1080 viewport, and window.matchMedia(q).matches
       # returns spec-correct booleans. Lets _lightpanda.isVisible detect
       # inline-@media-gated hides via el.checkVisibility() without any
-      # gem-side workaround. External <link rel="stylesheet"> fetch stays
-      # out of scope by design — see .claude/rules/lightpanda-io.md
-      # limitation #6).
-      # Build 6269 = first nightly carrying PR #2478 (merge commit
-      # ab63cfbf, 2026-05-16); the 2026-05-16 nightly cut at 03:36 UTC
-      # was hours before the merge at 13:42 UTC.
-      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6269")
+      # gem-side workaround),
+      # PR #2487 (css: external <link rel="stylesheet"> fetch behind the
+      # --enable-external-stylesheets flag — build_args now passes that flag
+      # unconditionally, so the floor MUST include the build that introduced
+      # it; the flag is a fatal UnknownOption on builds < 6353),
+      # PR #2498 (StyleManager: author display rule beats UA [hidden] — fixes
+      # the Stimulus/Alpine dropdown ElementNotFound).
+      # NOTE: the gem's teardown hang is the live-CDP-connection SIGTERM hang
+      # (limitation #7B) — telemetry-independent, present on 6353 AND on the #2509
+      # fix build, handled by the at_exit WS-close plus the SIGKILL backstop
+      # above. It is NOT #2507 (telemetry curl-multi, fixed by #2509): the gem
+      # disables telemetry, so it never creates the curl multi #2507 needs. Keep
+      # both teardown defenses even after #2511 (the variant-B fix, MERGED in
+      # build 6371) lands in a nightly.
+      # Build 6353 = main HEAD merge f1b0adf9 (2026-05-20) carrying #2487 +
+      # #2498; the first published nightly with it is the 2026-05-21 cut.
+      MINIMUM_NIGHTLY_BUILD = Gem::Version.new("6353")
 
       attr_reader :pid, :ws_url, :version, :nightly_build
 
@@ -89,23 +112,7 @@ module Capybara
       def stop
         return unless @pid
 
-        begin
-          ::Process.kill("TERM", -@pid) # Kill process group
-        rescue Errno::ESRCH, Errno::EPERM
-          # Process group already dead, try direct
-          begin
-            ::Process.kill("TERM", @pid)
-          rescue Errno::ESRCH
-            # Process already dead
-          end
-        end
-
-        begin
-          ::Process.wait(@pid)
-        rescue Errno::ECHILD
-          # Already reaped
-        end
-
+        self.class.send(:terminate, @pid)
         cleanup_pipes
         @pid = nil
       end
@@ -135,8 +142,7 @@ module Capybara
         raise BinaryError,
               "Lightpanda #{@version} is too old. " \
               "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}"
+              "Update: #{Binary.update_hint(binary_path)}"
       rescue Errno::ENOENT
         # Binary not runnable — let attempt_start handle it
       end
@@ -201,6 +207,10 @@ module Capybara
           @options.port.to_s,
           "--log_level",
           "info",
+          # External stylesheet fetch (PR #2487, build >= 6353 — enforced by the
+          # floor). Always on so linked CSS contributes to checkVisibility /
+          # getComputedStyle; see .claude/rules/lightpanda-io.md limitation #6.
+          "--enable-external-stylesheets",
         ]
         extra = ENV.fetch("LIGHTPANDA_EXTRA_ARGS", "").split
         base + extra
@@ -307,19 +317,59 @@ module Capybara
         end
       end
 
-      # Class method so the finalizer proc doesn't capture `self` (which
-      # would prevent GC from ever running the finalizer).
+      # Class methods so the finalizer proc doesn't capture `self` (which
+      # would prevent GC from ever running the finalizer). `terminate` is shared
+      # by the instance `#stop` and the finalizer so both escalate TERM -> KILL.
       class << self
         private
 
         def weak_kill(pid)
-          proc do
-            ::Process.kill("TERM", -pid)
+          proc { terminate(pid) }
+        end
+
+        # SIGTERM the process group, then SIGKILL if it hasn't exited within
+        # `grace` seconds; reap the child. Safe on an already-dead pid. The
+        # SIGKILL escalation is what keeps teardown from hanging on builds that
+        # ignore SIGTERM after serving CDP (see STOP_GRACE_SECONDS).
+        def terminate(pid, grace: STOP_GRACE_SECONDS)
+          signal(pid, "TERM")
+          return if reap_within(pid, grace)
+
+          signal(pid, "KILL")
+          begin
             ::Process.wait(pid)
-          rescue Errno::ESRCH, Errno::ECHILD, Errno::EPERM
+          rescue Errno::ECHILD
+            nil
+          end
+        end
+
+        # Signal the process group (-pid), falling back to the bare pid if the
+        # group send is rejected (ESRCH/EPERM).
+        def signal(pid, name)
+          ::Process.kill(name, -pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          begin
+            ::Process.kill(name, pid)
+          rescue Errno::ESRCH
             nil
           end
         end
+
+        # True once `pid` is reaped (or already gone); false if still alive
+        # after `seconds`.
+        def reap_within(pid, seconds)
+          deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + seconds
+          loop do
+            begin
+              return true if ::Process.wait(pid, ::Process::WNOHANG)
+            rescue Errno::ECHILD
+              return true
+            end
+            return false if ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) >= deadline
+
+            sleep 0.05
+          end
+        end
       end
 
       # `start` may be called more than once on the same Process instance

data/lib/capybara/lightpanda/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Lightpanda
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capybara-lightpanda
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Navid Emad