puppeteer-ruby 0.52.1 → 0.53.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70526928098a3ab1bcf1718b6110a6620188a30c77419a04181cb746acf4ed15
-  data.tar.gz: 073e09f7dd759b1b2b2d268ec3021cab96c3e56df93353343fd6ded898556d7b
+  metadata.gz: b9b4a8108523041a54e1d2e08af61b9ce13e8416451d321841e31e3ec609161b
+  data.tar.gz: 5075602b5392fa17b0d87cb566229d4ef31ef33e336b7d3c030fc71bea370b27
 SHA512:
-  metadata.gz: a222036f53e7552d12a8340850369aeed45277f44f1914984ff91168131fbc8ad0a93adf0a3ffe07b98e0f5038a14ee2da6239685bdbf297883bb2702d31df86
-  data.tar.gz: 57c5a117800a1b814d77abd3ad41d9b25487b08993e1752327dbac49a3e80474c612a52dd3141fd1025dd4fc96e5758c199a82de470abba73e290a5316db0516
+  metadata.gz: 2ba3f194f82a267372759a2c0cf25fb4dd3175513c68d6a463fb9b68cf13fed6ae05bb9941cbc7ce290042687e87e45e980ffe71e3c6bf869f5d367078818bd8
+  data.tar.gz: 62b6b3e7dd00894cb5789693c3a75b0003b44260a34273b3d24805c9642c2bb00a0e0e87a42571c6111a5ad3ff84cf5ac81e4fe0bccd339758c9d0d4a004be0e

data/docs/api_coverage.md

@@ -1,6 +1,6 @@
 # API coverages
-- Puppeteer version: v24.42.0
-- puppeteer-ruby version: 0.51.0
+- Puppeteer version: v25.3.0
+- puppeteer-ruby version: 0.53.0
 
 ## Puppeteer
 
@@ -10,9 +10,9 @@
 * launch
 * ~~puppeteer~~
 
-## ~~Accessibility~~
+## Accessibility
 
-* ~~snapshot~~
+* snapshot
 
 ## Browser
 
@@ -28,7 +28,6 @@
 * extensions
 * ~~getWindowBounds~~
 * installExtension => `#install_extension`
-* isConnected => `#connected?`
 * newPage => `#new_page`
 * pages
 * process
@@ -343,6 +342,7 @@
 * emulateCPUThrottling => `#emulate_cpu_throttling`
 * ~~emulateFocusedPage~~
 * emulateIdleState => `#emulate_idle_state`
+* emulateLocale => `#emulate_locale`
 * emulateMediaFeatures => `#emulate_media_features`
 * emulateMediaType => `#emulate_media_type`
 * emulateNetworkConditions => `#emulate_network_conditions`
@@ -360,7 +360,7 @@
 * goBack => `#go_back`
 * goForward => `#go_forward`
 * goto
-* ~~hasDevTools~~
+* hasDevTools => `#has_dev_tools`
 * hover
 * isClosed => `#closed?`
 * isDragInterceptionEnabled => `#drag_interception_enabled?`
@@ -369,14 +369,14 @@
 * locator
 * mainFrame => `#main_frame`
 * metrics
-* ~~openDevTools~~
+* openDevTools => `#open_dev_tools`
 * pdf
 * queryObjects => `#query_objects`
 * reload
 * removeExposedFunction => `#remove_exposed_function`
 * removeScriptToEvaluateOnNewDocument => `#remove_script_to_evaluate_on_new_document`
 * ~~resize~~
-* ~~screencast~~
+* screencast
 * screenshot
 * select
 * setBypassCSP => `#bypass_csp=`
@@ -423,9 +423,9 @@
 * ~~extension~~
 * ~~waitForFunction~~
 
-## ~~ScreenRecorder~~
+## ScreenRecorder
 
-* ~~stop~~
+* stop
 
 ## ~~SecurityDetails~~
 
@@ -469,15 +469,15 @@
 ## ~~UnsupportedOperation~~
 
 
-## ~~WebMCP~~
+## WebMCP
 
-* ~~tools~~
+* tools
 
-## ~~WebMCPTool~~
+## WebMCPTool
 
-* ~~execute~~
+* execute
 
-## ~~WebMCPToolCall~~
+## WebMCPToolCall
 
 
 ## WebWorker
@@ -486,3 +486,4 @@
 * evaluate
 * evaluateHandle => `#evaluate_handle`
 * url
+* waitForFunction => `#wait_for_function`

data/lib/puppeteer/accessibility.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Puppeteer::Accessibility
+  class SerializedAXNode < Hash #[String, untyped]
+    # @rbs values: Hash[String, untyped] -- Serialized node values
+    # @rbs element_handle_resolver: Proc -- Resolver for the backing element
+    def initialize(values, element_handle_resolver)
+      super()
+      update(values)
+      @element_handle_resolver = element_handle_resolver
+    end
+
+    # @rbs return: Puppeteer::ElementHandle? -- Backing element, if available
+    def element_handle
+      @element_handle_resolver.call
+    end
+  end
+
+  # @rbs frame: Puppeteer::Frame -- Frame whose accessibility tree is inspected
+  def initialize(frame)
+    @frame = frame
+  end
+
+  # @rbs interesting_only: bool -- Prune uninteresting nodes
+  # @rbs include_iframes: bool -- Include descendant iframe trees
+  # @rbs root: Puppeteer::ElementHandle? -- Optional root node
+  # @rbs return: SerializedAXNode? -- Accessibility snapshot
+  def snapshot(interesting_only: true, include_iframes: false, root: nil)
+    response = @frame.client.send_message(
+      'Accessibility.getFullAXTree',
+      frameId: @frame.id,
+    )
+    backend_node_id = describe_backend_node(root) if root
+    default_root = AXNode.create_tree(@frame, response.fetch('nodes', []))
+    return nil unless default_root
+
+    populate_iframes(default_root, interesting_only: interesting_only) if include_iframes
+
+    needle = default_root
+    if backend_node_id
+      needle = default_root.find do |node|
+        node.payload['backendDOMNodeId'] == backend_node_id
+      end
+    end
+    return nil unless needle
+
+    return serialize_tree(needle).first unless interesting_only
+
+    interesting_nodes = Set.new
+    collect_interesting_nodes(interesting_nodes, default_root, false)
+    serialize_tree(needle, interesting_nodes).first
+  end
+
+  private def describe_backend_node(root)
+    response = @frame.client.send_message(
+      'DOM.describeNode',
+      objectId: root.remote_object.object_id_value,
+    )
+    response.dig('node', 'backendNodeId')
+  end
+
+  private def populate_iframes(root, interesting_only:)
+    if root.role == 'Iframe' && root.payload['backendDOMNodeId']
+      begin
+        handle = @frame.main_world.adopt_backend_node(root.payload['backendDOMNodeId'])
+        frame = handle&.content_frame
+        root.iframe_snapshot = frame&.accessibility&.snapshot(
+          interesting_only: interesting_only,
+          include_iframes: true,
+        )
+      rescue StandardError
+        # Frames may detach while their accessibility trees are populated.
+      ensure
+        handle&.dispose
+      end
+    end
+
+    tasks = root.children.map do |child|
+      proc { populate_iframes(child, interesting_only: interesting_only) }
+    end
+    Puppeteer::AsyncUtils.await_promise_all(*tasks) unless tasks.empty?
+  end
+
+  private def serialize_tree(node, interesting_nodes = nil)
+    children = node.children.flat_map do |child|
+      serialize_tree(child, interesting_nodes)
+    end
+    return children if interesting_nodes && !interesting_nodes.include?(node)
+
+    serialized = node.serialize
+    serialized['children'] = children unless children.empty?
+    if node.iframe_snapshot
+      serialized['children'] ||= []
+      serialized['children'] << node.iframe_snapshot
+    end
+    [serialized]
+  end
+
+  private def collect_interesting_nodes(collection, node, inside_control)
+    collection << node if node.interesting?(inside_control) || node.iframe_snapshot
+    return if node.leaf_node?
+
+    inside_control ||= node.control?
+    node.children.each do |child|
+      collect_interesting_nodes(collection, child, inside_control)
+    end
+  end
+
+  class AXNode
+    CONTROL_ROLES = Set.new(%w[
+      button checkbox ColorWell combobox DisclosureTriangle listbox menu
+      menubar menuitem menuitemcheckbox menuitemradio radio scrollbar searchbox
+      slider spinbutton switch tab textbox tree treeitem
+    ]).freeze
+    LANDMARK_ROLES = Set.new(%w[
+      banner complementary contentinfo form main navigation region search
+    ]).freeze
+    LEAF_ROLES = Set.new(%w[
+      doc-cover graphics-symbol img image Meter scrollbar slider separator progressbar
+    ]).freeze
+    TEXT_ROLES = Set.new(%w[LineBreak text InlineTextBox StaticText]).freeze
+
+    # @rbs frame: Puppeteer::Frame -- Owning frame
+    # @rbs payload: Hash[String, untyped] -- CDP AX node payload
+    def initialize(frame, payload)
+      @frame = frame
+      @payload = payload
+      @children = []
+      @iframe_snapshot = nil
+      @role = payload.dig('role', 'value') || 'Unknown'
+      @ignored = payload['ignored']
+      @name = payload.dig('name', 'value') || ''
+      @description = payload.dig('description', 'value')
+      @richly_editable = false
+      @editable = false
+      @focusable = false
+      @hidden = false
+      @busy = false
+      @modal = false
+      @has_error_message = false
+      @has_details = false
+      @role_description = nil
+      @live = nil
+      @cached_has_focusable_child = nil
+      read_properties
+    end
+
+    attr_reader :payload, :children, :role
+    attr_accessor :iframe_snapshot
+
+    def find(&predicate)
+      return self if predicate.call(self)
+
+      @children.each do |child|
+        result = child.find(&predicate)
+        return result if result
+      end
+      nil
+    end
+
+    def leaf_node?
+      return true if @children.empty?
+      return true if plain_text_field? || TEXT_ROLES.include?(@role)
+      return true if LEAF_ROLES.include?(@role)
+      return false if has_focusable_child?
+      return true if @role == 'heading' && !@name.empty?
+
+      false
+    end
+
+    def control?
+      CONTROL_ROLES.include?(@role)
+    end
+
+    def landmark?
+      LANDMARK_ROLES.include?(@role)
+    end
+
+    def interesting?(inside_control)
+      return false if @role == 'Ignored' || @hidden || @ignored
+      return true if landmark?
+      return true if @focusable || @richly_editable || @busy
+      return true if @live && @live != 'off'
+      return true if @modal || @has_error_message || @has_details || @role_description
+      return true if control?
+      return false if inside_control
+
+      leaf_node? && (!@name.empty? || !@description.to_s.empty?)
+    end
+
+    def serialize
+      properties = {}
+      @payload.fetch('properties', []).each do |property|
+        properties[property['name'].downcase] = property.dig('value', 'value')
+      end
+      properties['name'] = @payload.dig('name', 'value') if @payload['name']
+      properties['value'] = @payload.dig('value', 'value') if @payload['value']
+      if @payload['description']
+        properties['description'] = @payload.dig('description', 'value')
+      end
+
+      values = {
+        'role' => @role,
+        'backendNodeId' => @payload['backendDOMNodeId'],
+        'loaderId' => @frame.loader_id,
+      }
+      %w[name value description keyshortcuts roledescription valuetext url].each do |key|
+        values[key] = properties[key] if properties.key?(key)
+      end
+      %w[
+        disabled expanded focused modal multiline multiselectable readonly required
+        selected busy atomic
+      ].each do |key|
+        next if key == 'focused' && @role == 'RootWebArea'
+        values[key] = !!properties[key] if properties.key?(key)
+      end
+      %w[checked pressed].each do |key|
+        next unless properties.key?(key)
+        value = properties[key]
+        values[key] = value == 'mixed' ? 'mixed' : value == 'true'
+      end
+      %w[level valuemax valuemin].each do |key|
+        values[key] = properties[key] if properties.key?(key)
+      end
+      %w[
+        autocomplete haspopup invalid orientation live relevant errormessage details
+      ].each do |key|
+        value = properties[key]
+        values[key] = value if value && value != 'false'
+      end
+      values.delete_if { |_key, value| value.nil? }
+
+      SerializedAXNode.new(values, method(:element_handle))
+    end
+
+    def self.create_tree(frame, payloads)
+      nodes_by_id = {}
+      payloads.each do |payload|
+        nodes_by_id[payload['nodeId']] = new(frame, payload)
+      end
+      nodes_by_id.each_value do |node|
+        node.payload.fetch('childIds', []).each do |child_id|
+          child = nodes_by_id[child_id]
+          node.children << child if child
+        end
+      end
+      nodes_by_id.each_value.first
+    end
+
+    private def read_properties
+      @payload.fetch('properties', []).each do |property|
+        name = property['name']
+        value = property.dig('value', 'value')
+        case name
+        when 'editable'
+          @richly_editable = value == 'richtext'
+          @editable = true
+        when 'focusable' then @focusable = value
+        when 'hidden' then @hidden = value
+        when 'busy' then @busy = value
+        when 'live' then @live = value
+        when 'modal' then @modal = value
+        when 'roledescription' then @role_description = value
+        when 'errormessage' then @has_error_message = true
+        when 'details' then @has_details = true
+        end
+      end
+    end
+
+    private def plain_text_field?
+      return false if @richly_editable
+      return true if @editable
+
+      ['textbox', 'searchbox'].include?(@role)
+    end
+
+    private def has_focusable_child?
+      if @cached_has_focusable_child.nil?
+        @cached_has_focusable_child = @children.any? do |child|
+          child.instance_variable_get(:@focusable) || child.send(:has_focusable_child?)
+        end
+      end
+      @cached_has_focusable_child
+    end
+
+    private def element_handle
+      backend_node_id = @payload['backendDOMNodeId']
+      return nil unless backend_node_id
+
+      handle = @frame.main_world.adopt_backend_node(backend_node_id)
+      element = handle.evaluate_handle(<<~JAVASCRIPT)
+        node => node.nodeType === Node.TEXT_NODE ? node.parentElement : node
+      JAVASCRIPT
+      element.as_element
+    ensure
+      handle&.dispose
+    end
+  end
+end

data/lib/puppeteer/browser.rb

@@ -16,6 +16,7 @@ class Puppeteer::Browser
   # @rbs network_enabled: bool -- Whether network events are enabled
   # @rbs issues_enabled: bool -- Whether issues events are enabled
   # @rbs block_list: Array[String]? -- URL block list patterns
+  # @rbs allow_list: Array[String]? -- URL allow list patterns
   # @rbs process: Puppeteer::BrowserRunner::BrowserProcess? -- Browser process handle
   # @rbs close_callback: Proc -- Close callback
   # @rbs target_filter_callback: Proc? -- Target filter callback
@@ -29,6 +30,7 @@ class Puppeteer::Browser
                   network_enabled: true,
                   issues_enabled: true,
                   block_list: nil,
+                  allow_list: nil,
                   process:,
                   close_callback:,
                   target_filter_callback:,
@@ -42,11 +44,13 @@ class Puppeteer::Browser
       network_enabled: network_enabled,
       issues_enabled: issues_enabled,
       block_list: block_list,
+      allow_list: allow_list,
       process: process,
       close_callback: close_callback,
       target_filter_callback: target_filter_callback,
       is_page_target_callback: is_page_target_callback,
     )
+    browser.send(:validate_allow_list_version)
     browser.send(:attach)
     browser
   end
@@ -59,6 +63,7 @@ class Puppeteer::Browser
   # @rbs network_enabled: bool -- Whether network events are enabled
   # @rbs issues_enabled: bool -- Whether issues events are enabled
   # @rbs block_list: Array[String]? -- URL block list patterns
+  # @rbs allow_list: Array[String]? -- URL allow list patterns
   # @rbs process: Puppeteer::BrowserRunner::BrowserProcess? -- Browser process handle
   # @rbs close_callback: Proc -- Close callback
   # @rbs target_filter_callback: Proc? -- Target filter callback
@@ -72,6 +77,7 @@ class Puppeteer::Browser
                  network_enabled: true,
                  issues_enabled: true,
                  block_list: nil,
+                 allow_list: nil,
                  process:,
                  close_callback:,
                  target_filter_callback:,
@@ -85,6 +91,7 @@ class Puppeteer::Browser
     @network_enabled = network_enabled
     @issues_enabled = issues_enabled
     @block_list = block_list
+    @allow_list = allow_list
     @process = process
     @connection = connection
     @close_callback = close_callback
@@ -102,14 +109,28 @@ class Puppeteer::Browser
       target_factory: method(:create_target),
       target_filter_callback: @target_filter_callback,
       block_list: block_list,
+      allow_list: allow_list,
     )
+    @connection.reject_emulate_network_conditions_calls =
+      [block_list, allow_list].any? { |list| list && !list.empty? }
     @extensions = {}
+    @version_promise = nil
   end
 
   private def default_target_filter_callback(target_info)
     true
   end
 
+  private def validate_allow_list_version
+    return unless @allow_list
+
+    product = version_info.product
+    major_version = product[/\d+/].to_i
+    if major_version < 149
+      raise Puppeteer::Error.new('The allow_list option requires Chrome 149 or greater.')
+    end
+  end
+
   private def default_is_page_target_callback(target_info)
     ['page', 'background_page', 'webview'].include?(target_info.type)
   end
@@ -261,7 +282,7 @@ class Puppeteer::Browser
   end
 
   private def handle_attached_to_target(target)
-    if target.initialized_promise.wait
+    if target.exposed? && target.initialized_promise.wait
       emit_event(BrowserEmittedEvents::TargetCreated, target)
       target.browser_context.emit_event(BrowserContextEmittedEvents::TargetCreated, target)
     end
@@ -270,7 +291,7 @@ class Puppeteer::Browser
   private def handle_detached_from_target(target)
     target.ignore_initialize_callback_promise
     target.closed_callback
-    if target.initialized_promise.wait
+    if target.exposed? && target.initialized_promise.wait
       emit_event(BrowserEmittedEvents::TargetDestroyed, target)
       target.browser_context.emit_event(BrowserContextEmittedEvents::TargetDestroyed, target)
     end
@@ -312,7 +333,7 @@ class Puppeteer::Browser
     }.compact
     result = @connection.send_message('Target.createTarget', **create_target_params)
     target_id = result['targetId']
-    target = @target_manager.available_targets[target_id]
+    target = wait_for_available_target(target_id)
     unless target
       raise MissingTargetError.new("Missing target for page (id = #{target_id})")
     end
@@ -326,11 +347,31 @@ class Puppeteer::Browser
     page
   end
 
+  private def wait_for_available_target(target_id)
+    target = @target_manager.available_targets[target_id]
+    return target if target
+
+    promise = Async::Promise.new
+    listener_id = @target_manager.add_event_listener(TargetManagerEmittedEvents::TargetAvailable) do |available_target|
+      if available_target.target_id == target_id && !promise.resolved?
+        promise.resolve(available_target)
+      end
+    end
+    target = @target_manager.available_targets[target_id]
+    return target if target
+
+    Puppeteer::AsyncUtils.async_timeout(30_000, promise).wait
+  rescue Async::TimeoutError
+    nil
+  ensure
+    @target_manager.remove_event_listener(listener_id) if listener_id
+  end
+
   # All active targets inside the Browser. In case of multiple browser contexts, returns
   # an array with all the targets in all browser contexts.
   # @rbs return: Array[Puppeteer::Target] -- Active targets
   def targets
-    @target_manager.available_targets.values.select { |target| target.initialized? }
+    @target_manager.available_targets.values.select { |target| target.exposed? && target.initialized? }
   end
 
 
@@ -386,12 +427,24 @@ class Puppeteer::Browser
 
   # @rbs return: String -- Browser version string
   def version
-    Version.fetch(@connection).product
+    version_info.product
   end
 
   # @rbs return: String -- Browser user agent string
   def user_agent
-    Version.fetch(@connection).user_agent
+    version_info.user_agent
+  end
+
+  private def version_info
+    unless @version_promise
+      @version_promise = Async::Promise.new
+      begin
+        @version_promise.resolve(Version.new(@connection.send_message('Browser.getVersion')))
+      rescue => error
+        @version_promise.reject(error)
+      end
+    end
+    @version_promise.wait
   end
 
   # @rbs page_target_id: String -- Page target id
@@ -401,10 +454,44 @@ class Puppeteer::Browser
     result['targetId']
   end
 
+  # @rbs page_target_id: String -- Inspected page target id
+  # @rbs return: Puppeteer::Page -- DevTools page
+  def _create_devtools_page(page_target_id)
+    result = @connection.send_message('Target.openDevTools', targetId: page_target_id)
+    _get_devtools_target_page(result['targetId'])
+  end
+
+  # @rbs devtools_target_id: String -- DevTools target id
+  # @rbs return: Puppeteer::Page -- DevTools page
+  def _get_devtools_target_page(devtools_target_id)
+    target = wait_for_available_target(devtools_target_id)
+    unless target
+      raise MissingTargetError.new(
+        "Missing target for DevTools page (id = #{devtools_target_id})",
+      )
+    end
+    unless target.initialized_promise.wait
+      raise CreatePageError.new(
+        "Failed to create target for DevTools page (id = #{devtools_target_id})",
+      )
+    end
+    page = target.as_page
+    unless page
+      raise CreatePageError.new(
+        "Failed to create a DevTools Page for target (id = #{devtools_target_id})",
+      )
+    end
+    page
+  end
+
   # @rbs path: String -- Extension path
+  # @rbs enabled_in_incognito: bool -- Enable in Incognito and OTR profiles
   # @rbs return: String -- Installed extension id
-  def install_extension(path)
-    result = @connection.send_message('Extensions.loadUnpacked', path: path)
+  def install_extension(path, enabled_in_incognito: false)
+    result = @connection.send_message('Extensions.loadUnpacked', {
+      path: path,
+      enableInIncognito: enabled_in_incognito,
+    })
     extension_id = result['id']
     @extensions.delete(extension_id)
     extension_id
@@ -414,6 +501,7 @@ class Puppeteer::Browser
   # @rbs return: void -- No return value
   def uninstall_extension(extension_id)
     @connection.send_message('Extensions.uninstall', id: extension_id)
+    @target_manager.remove_extension_service_workers(extension_id)
     @extensions.delete(extension_id)
   end
 
@@ -451,6 +539,17 @@ class Puppeteer::Browser
     @block_list
   end
 
+  # @rbs return: Array[String]? -- URL allow list patterns
+  def allow_list
+    @allow_list
+  end
+
+  # @rbs url: String -- URL to validate against network restriction rules
+  # @rbs return: bool -- Whether the URL is allowed
+  def url_allowed?(url)
+    @target_manager.url_allowed?(url)
+  end
+
   # @rbs return: void -- No return value
   def close
     @close_callback.call

data/lib/puppeteer/browser_connector.rb

@@ -32,6 +32,7 @@ class Puppeteer::BrowserConnector
       network_enabled: @browser_options.network_enabled,
       issues_enabled: @browser_options.issues_enabled,
       block_list: @browser_options.block_list,
+      allow_list: @browser_options.allow_list,
       process: nil,
       close_callback: -> { connection.send_message('Browser.close') },
       target_filter_callback: @browser_options.target_filter,

data/lib/puppeteer/browser_context.rb

@@ -241,7 +241,6 @@ class Puppeteer::BrowserContext
       if partition_key
         normalized['partitionKey'] = convert_partition_key_from_cdp(partition_key)
       end
-      normalized['sameParty'] = cookie['sameParty'] || false
       normalized
     end
   end