Class: Capybara::Lightpanda::Process

Inherits:
Object
  • Object
show all
Defined in:
lib/capybara/lightpanda/process.rb

Constant Summary collapse

READY_PATTERN = 
/server running.*address\s*=\s*(\d+\.\d+\.\d+\.\d+:\d+)/m
ADDRESS_IN_USE_PATTERN = 
/err=AddressInUse/
STOP_GRACE_SECONDS =

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.

3
MINIMUM_NIGHTLY_BUILD =

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), 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/), 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), PR #2352 (HTMLInputElement.pattern + patternMismatch via V8 RegExp), PR #2368 (events: report listener exceptions instead of halting dispatch — load-bearing for the gem’s JS bundle dispatch assumptions), PR #2289 (Page.getNavigationHistory + Page.navigateToHistoryEntry —lets us drop the history.back()/history.forward() JS workaround in Browser#back / #forward), PR #2305 (XPath 1.0: Document.evaluate, XPathResult, XPathEvaluator, XPathExpression — lets us drop the ~700 LOC XPath polyfill in javascripts/index.js), PR #2431 (cdp: remove duplicate Page.frameNavigated emission + reuse child frame’s V8 context — fixes issue #2400 iframe contextId churn, lets us drop Browser#find_in_frame’s refresh_frame_stack! rescue), PR #2445 (cdp: reset browser context arena on Target.disposeBrowserContext — restores per-spec state hygiene during Driver#reset!, cures the batch-mode pollution that PR #2431 alone exposed), PR #2435 (dom: implement HTMLDialogElement.showModal, close natively — load-bearing for the gem’s HTMLDialogElement assumptions after polyfills.js was deleted), PR #2450 (forms: add enctype + 5 submitter form-* IDL accessors + text/plain submission — lets us delete polyfills.js entirely; reads of form.enctype / submitter.formTarget now return spec-typed values natively), PR #2478 (css: evaluate @media and matchMedia against viewport —inline <style> @media blocks now apply declarations against the 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), 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.

Gem::Version.new("6353")

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Process

Returns a new instance of Process.



85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/capybara/lightpanda/process.rb', line 85

def initialize(options)
  @options = options
  @pid = nil
  @ws_url = nil
  @version = nil
  @nightly_build = nil
  @stdout_r = nil
  @stdout_w = nil
  @stderr_r = nil
  @stderr_w = nil
  @finalizer_registered = false
end

Instance Attribute Details

#nightly_build ⇒ Object (readonly)

Returns the value of attribute nightly_build.



83
84
85
 
# File 'lib/capybara/lightpanda/process.rb', line 83

def nightly_build
  @nightly_build
end

#pid ⇒ Object (readonly)

Returns the value of attribute pid.



83
84
85
 
# File 'lib/capybara/lightpanda/process.rb', line 83

def pid
  @pid
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



83
84
85
 
# File 'lib/capybara/lightpanda/process.rb', line 83

def version
  @version
end

#ws_url ⇒ Object (readonly)

Returns the value of attribute ws_url.



83
84
85
 
# File 'lib/capybara/lightpanda/process.rb', line 83

def ws_url
  @ws_url
end

Instance Method Details

#alive? ⇒ Boolean

Returns:

  • (Boolean) 


120
121
122
123
124
125
126
127
 
# File 'lib/capybara/lightpanda/process.rb', line 120

def alive?
  return false unless @pid

  ::Process.kill(0, @pid)
  true
rescue Errno::ESRCH, Errno::EPERM
  false
end

#start ⇒ Object 



98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/capybara/lightpanda/process.rb', line 98

def start
  binary_path = @options.browser_path || Binary.update

  raise BinaryNotFoundError, "Lightpanda binary not found" unless binary_path

  check_minimum_version(binary_path)
  attempt_start(binary_path)
rescue ProcessTimeoutError => e
  raise unless e.message.include?("already in use")

  kill_process_on_port(@options.port)
  attempt_start(binary_path)
end

#stop ⇒ Object 



112
113
114
115
116
117
118
 
# File 'lib/capybara/lightpanda/process.rb', line 112

def stop
  return unless @pid

  self.class.send(:terminate, @pid)
  cleanup_pipes
  @pid = nil
end