capybara-lightpanda 0.1.0

data/lib/capybara/lightpanda/options.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "logger"
+
+module Capybara
+  module Lightpanda
+    class Options
+      DEFAULT_TIMEOUT = ENV.fetch("LIGHTPANDA_DEFAULT_TIMEOUT", 15).to_i
+      DEFAULT_PROCESS_TIMEOUT = ENV.fetch("LIGHTPANDA_PROCESS_TIMEOUT", 10).to_i
+      DEFAULT_HOST = "127.0.0.1"
+      DEFAULT_PORT = 9222
+      DEFAULT_WINDOW_SIZE = [1024, 768].freeze
+
+      attr_accessor :host, :port, :timeout, :process_timeout, :window_size, :browser_path, :headless, :logger
+      attr_writer :ws_url
+
+      def initialize(options = {})
+        @host = options.fetch(:host, DEFAULT_HOST)
+        @port = options.fetch(:port, DEFAULT_PORT)
+        @timeout = options.fetch(:timeout, DEFAULT_TIMEOUT)
+        @process_timeout = options.fetch(:process_timeout, DEFAULT_PROCESS_TIMEOUT)
+        @window_size = options.fetch(:window_size, DEFAULT_WINDOW_SIZE)
+        @browser_path = options[:browser_path]
+        @headless = options.fetch(:headless, true)
+        @ws_url = options[:ws_url]
+        @logger = parse_logger(options[:logger])
+      end
+
+      def ws_url
+        @ws_url || "ws://#{host}:#{port}/"
+      end
+
+      def ws_url?
+        !@ws_url.nil?
+      end
+
+      def to_h
+        h = {
+          host: host,
+          port: port,
+          timeout: timeout,
+          process_timeout: process_timeout,
+          window_size: window_size,
+          browser_path: browser_path,
+          headless: headless,
+          logger: logger,
+        }
+        h[:ws_url] = @ws_url if @ws_url
+        h
+      end
+
+      private
+
+      def parse_logger(logger)
+        return logger if logger.is_a?(Capybara::Lightpanda::Logger)
+        return Capybara::Lightpanda::Logger.new(logger) if logger
+        return Capybara::Lightpanda::Logger.new($stdout.tap { |s| s.sync = true }) if ENV["LIGHTPANDA_DEBUG"]
+
+        Capybara::Lightpanda::Logger.new
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/process.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Process
+      READY_PATTERN = /server running.*address=(\d+\.\d+\.\d+\.\d+:\d+)/
+      ADDRESS_IN_USE_PATTERN = /err=AddressInUse/
+
+      # First nightly with Page.addScriptToEvaluateOnNewDocument (PR #1993, merged 2026-03-30).
+      # The gem relies on this for XPath polyfill auto-injection.
+      MINIMUM_NIGHTLY_BUILD = 5267
+
+      attr_reader :pid, :ws_url, :version, :nightly_build
+
+      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
+      end
+
+      def start
+        binary_path = @options.browser_path || Binary.find_or_download
+
+        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
+
+      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
+
+        cleanup_pipes
+        @pid = nil
+      end
+
+      def alive?
+        return false unless @pid
+
+        ::Process.kill(0, @pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+
+      private
+
+      def check_minimum_version(binary_path)
+        stdout, = Open3.capture3(binary_path, "version")
+        @version = stdout.strip
+        @nightly_build = @version[/nightly\.(\d+)/, 1]&.to_i
+
+        return if @nightly_build && @nightly_build >= MINIMUM_NIGHTLY_BUILD
+
+        raise BinaryError,
+              "Lightpanda #{@version} is too old. " \
+              "This gem requires nightly build >= #{MINIMUM_NIGHTLY_BUILD} " \
+              "(Page.addScriptToEvaluateOnNewDocument support). " \
+              "Update: curl -sL https://github.com/lightpanda-io/browser/releases/download/nightly/" \
+              "#{Binary.platform_binary} -o #{binary_path} && chmod +x #{binary_path}"
+      rescue Errno::ENOENT
+        # Binary not runnable — let attempt_start handle it
+      end
+
+      def attempt_start(binary_path)
+        @stdout_r, @stdout_w = IO.pipe
+        @stderr_r, @stderr_w = IO.pipe
+
+        @pid = spawn_process(binary_path)
+        register_finalizer(@pid)
+
+        @stdout_w.close
+        @stderr_w.close
+
+        wait_for_ready
+
+        # Drain stderr/stdout to prevent pipe buffer from filling up
+        # and blocking the Lightpanda process
+        start_drain_thread
+      end
+
+      def start_drain_thread
+        @drain_thread = Thread.new do
+          ios = [@stdout_r, @stderr_r].compact
+          loop do
+            ready = IO.select(ios, nil, nil, 0.5)
+            next unless ready
+
+            ready[0].each do |io|
+              io.read_nonblock(4096)
+            rescue IO::WaitReadable
+              # No data
+            rescue EOFError
+              ios.delete(io)
+            end
+
+            break if ios.empty?
+          rescue IOError
+            break
+          end
+        end
+      end
+
+      def spawn_process(binary_path)
+        args = build_args
+
+        ::Process.spawn(
+          { "LIGHTPANDA_DISABLE_TELEMETRY" => "true" },
+          binary_path, *args,
+          out: @stdout_w,
+          err: @stderr_w,
+          pgroup: true
+        )
+      end
+
+      def build_args
+        [
+          "serve",
+          "--host",
+          @options.host.to_s,
+          "--port",
+          @options.port.to_s,
+          "--log_level",
+          "info",
+        ]
+      end
+
+      def wait_for_ready
+        started_at = Time.now
+        output = +""
+
+        catch(:ready) do
+          while Time.now - started_at < @options.process_timeout
+            ready = IO.select([@stdout_r, @stderr_r], nil, nil, 0.1)
+
+            next unless ready
+
+            ready[0].each do |io|
+              chunk = io.read_nonblock(1024)
+              output << chunk
+
+              if (match = output.match(READY_PATTERN))
+                @ws_url = "ws://#{match[1]}/"
+                throw(:ready)
+              end
+
+              if output.match?(ADDRESS_IN_USE_PATTERN)
+                cleanup_failed_process
+                raise ProcessTimeoutError,
+                      "Lightpanda failed to start: port #{@options.port} is already in use"
+              end
+            rescue IO::WaitReadable
+              # No data available yet
+            rescue EOFError
+              # Pipe closed
+            end
+          end
+
+          stop
+
+          raise ProcessTimeoutError,
+                "Lightpanda failed to start within #{@options.process_timeout} seconds.\nOutput: #{output}"
+        end
+      end
+
+      def cleanup_failed_process
+        return unless @pid
+
+        begin
+          ::Process.wait(@pid, ::Process::WNOHANG)
+        rescue Errno::ECHILD
+          nil
+        end
+
+        cleanup_pipes
+        @pid = nil
+      end
+
+      def kill_process_on_port(port)
+        port = port.to_i
+        return if port <= 0
+
+        pids = `lsof -ti tcp:#{port} 2>/dev/null`.strip
+        return if pids.empty?
+
+        pids.split("\n").each do |pid_str|
+          pid = pid_str.strip.to_i
+          next if pid <= 0
+
+          ::Process.kill("TERM", pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+
+        sleep 0.5
+      end
+
+      # Class method so the finalizer proc doesn't capture `self` (which
+      # would prevent GC from ever running the finalizer).
+      class << self
+        private
+
+        def weak_kill(pid)
+          proc do
+            ::Process.kill("TERM", -pid)
+            ::Process.wait(pid)
+          rescue Errno::ESRCH, Errno::ECHILD, Errno::EPERM
+            nil
+          end
+        end
+      end
+
+      def register_finalizer(pid)
+        ObjectSpace.define_finalizer(self, self.class.send(:weak_kill, pid))
+      end
+
+      def cleanup_pipes
+        [@stdout_r, @stdout_w, @stderr_r, @stderr_w].each do |pipe|
+          pipe&.close unless pipe&.closed?
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/utils/event.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module Capybara
+  module Lightpanda
+    module Utils
+      # Concurrent::Event with an iteration counter so callers can detect
+      # that the event was reset (e.g. a new navigation started) while they
+      # were waiting on it. Mirrors ferrum's Utils::Event.
+      #
+      # The base Concurrent::Event allows wait/set/reset cycles, but a wait
+      # that returns true after a reset → set is indistinguishable from one
+      # that returned true on the original set. The iteration counter,
+      # bumped on every reset, lets callers compare before and after to
+      # tell whether the event was raced by a reset.
+      class Event < Concurrent::Event
+        def initialize
+          super
+          @iteration = 0
+        end
+
+        def iteration
+          synchronize { @iteration }
+        end
+
+        def reset
+          synchronize do
+            @iteration += 1
+            @set = false if @set
+            @iteration
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    VERSION = "0.1.0"
+  end
+end

data/lib/capybara/lightpanda/xpath_polyfill.rb

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

data/lib/capybara-lightpanda.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "capybara"
+
+require_relative "capybara/lightpanda/version"
+require_relative "capybara/lightpanda/errors"
+require_relative "capybara/lightpanda/logger"
+require_relative "capybara/lightpanda/options"
+require_relative "capybara/lightpanda/binary"
+require_relative "capybara/lightpanda/process"
+require_relative "capybara/lightpanda/utils/event"
+require_relative "capybara/lightpanda/client"
+require_relative "capybara/lightpanda/network"
+require_relative "capybara/lightpanda/cookies"
+require_relative "capybara/lightpanda/keyboard"
+require_relative "capybara/lightpanda/frame"
+require_relative "capybara/lightpanda/browser"
+require_relative "capybara/lightpanda/xpath_polyfill"
+require_relative "capybara/lightpanda/node"
+require_relative "capybara/lightpanda/driver"
+
+module Capybara
+  module Lightpanda
+    class << self
+      def configure
+        yield(options) if block_given?
+      end
+
+      def options
+        @options ||= Options.new
+      end
+
+      def reset_options!
+        @options = nil
+      end
+    end
+  end
+end
+
+Capybara.register_driver(:lightpanda) do |app|
+  Capybara::Lightpanda::Driver.new(app, Capybara::Lightpanda.options.to_h)
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: capybara-lightpanda
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Navid Emad
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: A Capybara driver for Lightpanda, the fast headless browser built in
+  Zig. Provides a production-ready driver with XPath polyfill, reliable navigation,
+  and cookie management — ready for real-world Rails test suites.
+email:
+- design.navid@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- NOTICE.md
+- README.md
+- lib/capybara-lightpanda.rb
+- lib/capybara/lightpanda/binary.rb
+- lib/capybara/lightpanda/browser.rb
+- lib/capybara/lightpanda/client.rb
+- lib/capybara/lightpanda/client/subscriber.rb
+- lib/capybara/lightpanda/client/web_socket.rb
+- lib/capybara/lightpanda/cookies.rb
+- lib/capybara/lightpanda/driver.rb
+- lib/capybara/lightpanda/errors.rb
+- lib/capybara/lightpanda/frame.rb
+- lib/capybara/lightpanda/javascripts/index.js
+- lib/capybara/lightpanda/keyboard.rb
+- lib/capybara/lightpanda/logger.rb
+- lib/capybara/lightpanda/network.rb
+- lib/capybara/lightpanda/node.rb
+- lib/capybara/lightpanda/options.rb
+- lib/capybara/lightpanda/process.rb
+- lib/capybara/lightpanda/utils/event.rb
+- lib/capybara/lightpanda/version.rb
+- lib/capybara/lightpanda/xpath_polyfill.rb
+homepage: https://navidemad.github.io/capybara-lightpanda
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/navidemad/capybara-lightpanda
+  changelog_uri: https://github.com/navidemad/capybara-lightpanda/releases
+  bug_tracker_uri: https://github.com/navidemad/capybara-lightpanda/issues
+  documentation_uri: https://navidemad.github.io/capybara-lightpanda
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Capybara driver for the Lightpanda headless browser
+test_files: []