puppeteer-ruby 0.45.6 → 0.50.0.alpha5

data/lib/puppeteer/puppeteer.rb

@@ -1,7 +1,10 @@
+# rbs_inline: enabled
+
 class Puppeteer::Puppeteer
-  # @param project_root [String]
-  # @param prefereed_revision [String]
-  # @param is_puppeteer_core [String]
+  # @rbs project_root: String -- Project root directory
+  # @rbs preferred_revision: String -- Preferred Chromium revision
+  # @rbs is_puppeteer_core: bool -- Whether puppeteer-core mode is enabled
+  # @rbs return: void -- No return value
   def initialize(project_root:, preferred_revision:, is_puppeteer_core:)
     @project_root = project_root
     @preferred_revision = preferred_revision
@@ -10,25 +13,30 @@ class Puppeteer::Puppeteer
 
   class NoViewport ; end
 
-  # @param product [String]
-  # @param channel [String|Symbol]
-  # @param executable_path [String]
-  # @param ignore_default_args [Array<String>|nil]
-  # @param handle_SIGINT [Boolean]
-  # @param handle_SIGTERM [Boolean]
-  # @param handle_SIGHUP [Boolean]
-  # @param timeout [Integer]
-  # @param dumpio [Boolean]
-  # @param env [Hash]
-  # @param pipe [Boolean]
-  # @param args [Array<String>]
-  # @param user_data_dir [String]
-  # @param devtools [Boolean]
-  # @param headless [Boolean]
-  # @param ignore_https_errors [Boolean]
-  # @param default_viewport [Puppeteer::Viewport|nil]
-  # @param slow_mo [Integer]
-  # @return [Puppeteer::Browser]
+  # @rbs product: String? -- Browser product (chrome only)
+  # @rbs channel: (String | Symbol)? -- Browser channel
+  # @rbs executable_path: String? -- Path to browser executable
+  # @rbs ignore_default_args: Array[String]? -- Arguments to exclude from defaults
+  # @rbs handle_SIGINT: bool? -- Handle SIGINT in browser process
+  # @rbs handle_SIGTERM: bool? -- Handle SIGTERM in browser process
+  # @rbs handle_SIGHUP: bool? -- Handle SIGHUP in browser process
+  # @rbs timeout: Integer? -- Launch timeout in milliseconds
+  # @rbs dumpio: bool? -- Pipe browser stdout/stderr to current process
+  # @rbs env: Hash[String, String]? -- Environment variables for browser
+  # @rbs pipe: bool? -- Use pipe instead of WebSocket
+  # @rbs args: Array[String]? -- Additional browser arguments
+  # @rbs user_data_dir: String? -- Path to user data directory
+  # @rbs devtools: bool? -- Auto-open DevTools
+  # @rbs debugging_port: Integer? -- Remote debugging port
+  # @rbs headless: bool? -- Run browser in headless mode
+  # @rbs ignore_https_errors: bool? -- Ignore HTTPS errors
+  # @rbs network_enabled: bool? -- Enable network domain
+  # @rbs default_viewport: Puppeteer::Viewport? -- Default viewport
+  # @rbs slow_mo: Integer? -- Delay between operations (ms)
+  # @rbs protocol_timeout: Integer? -- CDP protocol timeout in milliseconds
+  # @rbs wait_for_initial_page: bool? -- Wait for initial page to load
+  # @rbs block: Proc? -- Optional block receiving the browser
+  # @rbs return: Puppeteer::Browser -- Browser instance
   def launch(
     product: nil,
     channel: nil,
@@ -47,9 +55,18 @@ class Puppeteer::Puppeteer
     debugging_port: nil,
     headless: nil,
     ignore_https_errors: nil,
+    network_enabled: true,
     default_viewport: NoViewport.new,
-    slow_mo: nil
+    slow_mo: nil,
+    protocol_timeout: nil,
+    wait_for_initial_page: nil,
+    &block
   )
+    product = product.to_s if product
+    if product && product != 'chrome'
+      raise ArgumentError.new("Unsupported product: #{product}. Only 'chrome' is supported.")
+    end
+
     options = {
       channel: channel&.to_s,
       executable_path: executable_path,
@@ -67,62 +84,115 @@ class Puppeteer::Puppeteer
       debugging_port: debugging_port,
       headless: headless,
       ignore_https_errors: ignore_https_errors,
+      network_enabled: network_enabled,
       default_viewport: default_viewport,
       slow_mo: slow_mo,
+      protocol_timeout: protocol_timeout,
+      wait_for_initial_page: wait_for_initial_page,
     }
     if default_viewport.is_a?(NoViewport)
       options.delete(:default_viewport)
     end
+    options.delete(:wait_for_initial_page) if wait_for_initial_page.nil?
 
     @product_name = product
-    browser = launcher.launch(options)
-    if block_given?
-      begin
-        yield(browser)
-      ensure
-        browser.close
+    if async_context?
+      browser = launcher.launch(options)
+      if block
+        begin
+          block.call(browser)
+        ensure
+          browser.close
+        end
+      else
+        browser
       end
     else
-      browser
+      runner = Puppeteer::ReactorRunner.new
+      begin
+        browser = runner.sync { launcher.launch(options) }
+      rescue StandardError
+        runner.close
+        raise
+      end
+      proxy = Puppeteer::ReactorRunner::Proxy.new(runner, browser, owns_runner: true)
+      if block
+        begin
+          block.call(proxy)
+        ensure
+          proxy.close
+        end
+      else
+        proxy
+      end
     end
   end
 
-  # @param browser_ws_endpoint [String]
-  # @param browser_url [String]
-  # @param transport [Puppeteer::WebSocketTransport]
-  # @param ignore_https_errors [Boolean]
-  # @param default_viewport [Puppeteer::Viewport|nil]
-  # @param slow_mo [Integer]
-  # @return [Puppeteer::Browser]
+  # @rbs browser_ws_endpoint: String? -- Browser WebSocket endpoint
+  # @rbs browser_url: String? -- Browser HTTP URL for WebSocket discovery
+  # @rbs transport: Puppeteer::WebSocketTransport? -- Pre-connected transport
+  # @rbs ignore_https_errors: bool? -- Ignore HTTPS errors
+  # @rbs network_enabled: bool? -- Enable network domain
+  # @rbs default_viewport: Puppeteer::Viewport? -- Default viewport
+  # @rbs slow_mo: Integer? -- Delay between operations (ms)
+  # @rbs protocol_timeout: Integer? -- CDP protocol timeout in milliseconds
+  # @rbs block: Proc? -- Optional block receiving the browser
+  # @rbs return: Puppeteer::Browser -- Browser instance
   def connect(
     browser_ws_endpoint: nil,
     browser_url: nil,
     transport: nil,
     ignore_https_errors: nil,
+    network_enabled: true,
     default_viewport: nil,
-    slow_mo: nil
+    slow_mo: nil,
+    protocol_timeout: nil,
+    &block
   )
     options = {
       browser_ws_endpoint: browser_ws_endpoint,
       browser_url: browser_url,
       transport: transport,
       ignore_https_errors: ignore_https_errors,
+      network_enabled: network_enabled,
       default_viewport: default_viewport,
       slow_mo: slow_mo,
+      protocol_timeout: protocol_timeout,
     }.compact
-    browser = Puppeteer::BrowserConnector.new(options).connect_to_browser
-    if block_given?
-      begin
-        yield(browser)
-      ensure
-        browser.disconnect
+    if async_context?
+      browser = Puppeteer::BrowserConnector.new(options).connect_to_browser
+      if block
+        begin
+          block.call(browser)
+        ensure
+          browser.disconnect
+        end
+      else
+        browser
       end
     else
-      browser
+      runner = Puppeteer::ReactorRunner.new
+      begin
+        browser = runner.sync { Puppeteer::BrowserConnector.new(options).connect_to_browser }
+      rescue StandardError
+        runner.close
+        raise
+      end
+      proxy = Puppeteer::ReactorRunner::Proxy.new(runner, browser, owns_runner: true)
+      if block
+        begin
+          block.call(proxy)
+        ensure
+          proxy.disconnect
+        end
+      else
+        proxy
+      end
     end
   end
 
-  # @return [String]
+  # @rbs channel: String? -- Browser channel
+  # @rbs return: String -- Executable path
   def executable_path(channel: nil)
     launcher.executable_path(channel: channel)
   end
@@ -136,34 +206,56 @@ class Puppeteer::Puppeteer
     )
   end
 
-  # @return [String]
+  # @rbs return: String -- Product name
   def product
     launcher.product
   end
 
-  def register_custom_query_handler(name:, query_one:, query_all:)
+  private def async_context?
+    task = Async::Task.current
+    !task.nil?
+  rescue RuntimeError, NoMethodError
+    false
+  end
+
+  # @rbs name: String -- Custom query handler name
+  # @rbs query_one: String? -- Query-one handler
+  # @rbs query_all: String? -- Query-all handler
+  # @rbs return: void -- No return value
+  def register_custom_query_handler(name:, query_one: nil, query_all: nil)
     unless name =~ /\A[a-zA-Z]+\z/
       raise ArgumentError.new("Custom query handler names may only contain [a-zA-Z]")
     end
 
+    if query_one.nil? && query_all.nil?
+      raise ArgumentError.new('At least one query method must be implemented.')
+    end
+
+    handler = Puppeteer::CustomQueryHandler.new(query_one: query_one, query_all: query_all)
     handler_name = name.to_sym
     if query_handler_manager.query_handlers.key?(handler_name)
       raise ArgumentError.new("A query handler named #{name} already exists")
     end
 
-    handler = Puppeteer::CustomQueryHandler.new(query_one: query_one, query_all: query_all)
-    Puppeteer::QueryHandlerManager.instance.query_handlers[handler_name] = handler
+    query_handler_manager.query_handlers[handler_name] = handler
   end
 
-  def with_custom_query_handler(name:, query_one:, query_all:, &block)
+  # @rbs name: String -- Custom query handler name
+  # @rbs query_one: String? -- Query-one handler
+  # @rbs query_all: String? -- Query-all handler
+  # @rbs return: untyped -- Block result
+  def with_custom_query_handler(name:, query_one: nil, query_all: nil, &block)
     unless name =~ /\A[a-zA-Z]+\z/
       raise ArgumentError.new("Custom query handler names may only contain [a-zA-Z]")
     end
 
+    if query_one.nil? && query_all.nil?
+      raise ArgumentError.new('At least one query method must be implemented.')
+    end
+
     handler_name = name.to_sym
 
     handler = Puppeteer::CustomQueryHandler.new(query_one: query_one, query_all: query_all)
-    query_handler_manager = Puppeteer::QueryHandlerManager.instance
     original = query_handler_manager.query_handlers.delete(handler_name)
     query_handler_manager.query_handlers[handler_name] = handler
     begin
@@ -177,26 +269,41 @@ class Puppeteer::Puppeteer
     end
   end
 
-  # @return [Puppeteer::Devices]
+  # @rbs name: String -- Custom query handler name
+  # @rbs return: void -- No return value
+  def unregister_custom_query_handler(name:)
+    query_handler_manager.unregister_custom_query_handler(name)
+  end
+
+  # @rbs return: void -- No return value
+  def clear_custom_query_handlers
+    query_handler_manager.clear_custom_query_handlers
+  end
+
+  # @rbs return: Array[String] -- Registered custom query handler names
+  def custom_query_handler_names
+    query_handler_manager.custom_query_handler_names
+  end
+
+  private def query_handler_manager
+    Puppeteer::QueryHandlerManager.instance
+  end
+
+  # @rbs return: Puppeteer::Devices -- Devices registry
   def devices
     Puppeteer::Devices
   end
 
-  # # @return {Object}
-  # def errors
-  #   # ???
-  # end
-
-  # @return [Puppeteer::NetworkConditions]
+  # @rbs return: Puppeteer::NetworkConditions -- Network conditions registry
   def network_conditions
     Puppeteer::NetworkConditions
   end
 
-  # @param args [Array<String>]
-  # @param user_data_dir [String]
-  # @param devtools [Boolean]
-  # @param headless [Boolean]
-  # @return [Array<String>]
+  # @rbs args: Array[String]? -- Additional arguments
+  # @rbs user_data_dir: String? -- Path to user data directory
+  # @rbs devtools: bool? -- Enable DevTools
+  # @rbs headless: bool? -- Run browser in headless mode
+  # @rbs return: Array[String] -- Default launch arguments
   def default_args(args: nil, user_data_dir: nil, devtools: nil, headless: nil)
     options = {
       args: args,

data/lib/puppeteer/query_handler_manager.rb

@@ -3,6 +3,8 @@ require 'singleton'
 class Puppeteer::QueryHandlerManager
   include Singleton
 
+  DEFAULT_QUERY_HANDLER_NAMES = %i[aria xpath text].freeze
+
   def query_handlers
     @query_handlers ||= {
       aria: Puppeteer::AriaQueryHandler.new,
@@ -11,6 +13,30 @@ class Puppeteer::QueryHandlerManager
     }
   end
 
+  def custom_query_handler_names
+    query_handlers.keys.reject { |name| DEFAULT_QUERY_HANDLER_NAMES.include?(name) }.map(&:to_s)
+  end
+
+  def unregister_custom_query_handler(name)
+    handler_name = name.to_sym
+    if DEFAULT_QUERY_HANDLER_NAMES.include?(handler_name)
+      raise ArgumentError.new("Cannot unregister built-in query handler: #{name}")
+    end
+    unless query_handlers.key?(handler_name)
+      raise ArgumentError.new("Cannot unregister unknown handler: #{name}")
+    end
+
+    query_handlers.delete(handler_name)
+  end
+
+  def clear_custom_query_handlers
+    query_handlers.each_key do |name|
+      next if DEFAULT_QUERY_HANDLER_NAMES.include?(name)
+
+      query_handlers.delete(name)
+    end
+  end
+
   private def default_handler
     @default_handler ||= Puppeteer::CustomQueryHandler.new(
       query_one: '(element, selector) => element.querySelector(selector)',
@@ -18,6 +44,65 @@ class Puppeteer::QueryHandlerManager
     )
   end
 
+  private def p_query_handler
+    @p_query_handler ||= Puppeteer::CustomQueryHandler.new(
+      query_one: <<~JAVASCRIPT,
+      (element, selector) => {
+        const parts = selector.split('>>>').map((part) => part.trim()).filter(Boolean);
+        let roots = [element];
+        if (parts.length === 0) return null;
+        for (let i = 0; i < parts.length; i++) {
+          const part = parts[i];
+          const next = [];
+          for (const root of roots) {
+            const scope = root;
+            const elements = scope.querySelectorAll(part);
+            for (const node of elements) {
+              if (i === parts.length - 1) {
+                next.push(node);
+              } else if (node.shadowRoot) {
+                next.push(node.shadowRoot);
+              }
+            }
+          }
+          if (i === parts.length - 1) {
+            return next[0] || null;
+          }
+          roots = next;
+        }
+        return null;
+      }
+      JAVASCRIPT
+      query_all: <<~JAVASCRIPT,
+      (element, selector) => {
+        const parts = selector.split('>>>').map((part) => part.trim()).filter(Boolean);
+        let roots = [element];
+        if (parts.length === 0) return [];
+        for (let i = 0; i < parts.length; i++) {
+          const part = parts[i];
+          const next = [];
+          for (const root of roots) {
+            const scope = root;
+            const elements = scope.querySelectorAll(part);
+            for (const node of elements) {
+              if (i === parts.length - 1) {
+                next.push(node);
+              } else if (node.shadowRoot) {
+                next.push(node.shadowRoot);
+              }
+            }
+          }
+          if (i === parts.length - 1) {
+            return next;
+          }
+          roots = next;
+        }
+        return [];
+      }
+      JAVASCRIPT
+    )
+  end
+
   private def xpath_handler
     @xpath_handler ||= Puppeteer::CustomQueryHandler.new(
       query_one: <<~JAVASCRIPT,
@@ -203,9 +288,10 @@ class Puppeteer::QueryHandlerManager
   end
 
   class Result
-    def initialize(query_handler:, selector:)
+    def initialize(query_handler:, selector:, polling:)
       @query_handler = query_handler
       @selector = selector
+      @polling = polling
     end
 
     def query_one(element_handle)
@@ -213,7 +299,14 @@ class Puppeteer::QueryHandlerManager
     end
 
     def wait_for(element_or_frame, visible:, hidden:, timeout:)
-      @query_handler.wait_for(element_or_frame, @selector, visible: visible, hidden: hidden, timeout: timeout)
+      @query_handler.wait_for(
+        element_or_frame,
+        @selector,
+        visible: visible,
+        hidden: hidden,
+        timeout: timeout,
+        polling: @polling,
+      )
     end
 
     def query_all(element_handle)
@@ -226,26 +319,29 @@ class Puppeteer::QueryHandlerManager
   end
 
   def detect_query_handler(selector)
-    unless /^[a-zA-Z]+\// =~ selector
-      return Result.new(
-        query_handler: default_handler,
-        selector: selector,
-      )
-    end
-
-    chunk = selector.split("/")
-    name = chunk.shift
-    updated_selector = chunk.join("/")
-
-    query_handler = query_handlers[name.to_sym]
+    query_handler = nil
+    updated_selector = selector
+    polling = selector.include?(':') ? 'raf' : 'mutation'
 
-    unless query_handler
-      raise ArgumentError.new("Query set to use \"#{name}\", but no query handler of that name was found")
+    if (match = selector.match(/^([a-zA-Z][\w-]*)([=\/])(.*)$/))
+      name = match[1]
+      updated_selector = match[3]
+      query_handler = query_handlers[name.to_sym]
+      unless query_handler
+        raise ArgumentError.new("Query set to use \"#{name}\", but no query handler of that name was found")
+      end
+      polling = name == 'aria' ? 'raf' : 'mutation'
+    elsif selector.include?('>>>')
+      query_handler = p_query_handler
+      polling = 'raf'
+    else
+      query_handler = default_handler
     end
 
     Result.new(
       query_handler: query_handler,
       selector: updated_selector,
+      polling: polling,
     )
   end
 end