feat: add page.accessibility CDP domain API

CHANGELOG.md

@@ -4,6 +4,7 @@
 - `Ferrum::Frame#loader_id` provides a loader id when frame navigates [#583]
 - `Ferrum::Frame#lifecycle_events` provides a list of frame's events like init, networkIdle, firstPaint, etc. [#583]
 - `Ferrum::Frame#idle?` whether frame was loaded [#583]
+- `page.accessibility` API and `Node#axnode` for reading the CDP accessibility tree
 
 ### Changed
 - `Ferrum::PendingConnectionsError` and `Ferrum::TimeoutError` were swallowed even though happening when traffic iterator results in empty array. [#583]

lib/ferrum/accessibility.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "ferrum/accessibility/ax_node"
+
+module Ferrum
+  #
+  # Wraps the CDP [Accessibility](https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/)
+  # domain. The query commands work without `enable`; `enable`/`disable` are
+  # provided for completeness (live AX events).
+  #
+  # @note The node-scoped methods (`node_for`, `partial_tree`, `query` with a
+  #   `node:`) issue the command against the node's owning page session. They
+  #   support same-process (same-target) iframes; nodes living in an
+  #   out-of-process iframe (OOPIF, separate CDP target) are not resolvable and
+  #   will error or return an empty result.
+  #
+  class Accessibility
+    def initialize(page)
+      @page = page
+    end
+
+    #
+    # The single non-ignored AXNode for a DOM node, or `nil`.
+    #
+    # @param [Ferrum::Node] node
+    # @return [AXNode, nil]
+    #
+    def node_for(node)
+      partial_tree(node: node).find { |ax_node| !ax_node.ignored? }
+    end
+
+    #
+    # The partial AX tree for a DOM node.
+    #
+    # @param [Ferrum::Node] node
+    # @param [Boolean] fetch_relatives
+    # @return [Array<AXNode>]
+    #
+    def partial_tree(node:, fetch_relatives: false)
+      nodes = node.page.command("Accessibility.getPartialAXTree",
+                                nodeId: node.node_id,
+                                fetchRelatives: fetch_relatives)["nodes"]
+      build(nodes)
+    end
+
+    #
+    # The full AX tree for the page.
+    #
+    # @param [Integer, nil] depth
+    # @param [String, nil] frame_id
+    # @return [Array<AXNode>]
+    #
+    def snapshot(depth: nil, frame_id: nil)
+      params = { depth: depth, frameId: frame_id }.compact
+      build(@page.command("Accessibility.getFullAXTree", **params)["nodes"])
+    end
+
+    #
+    # Query the AX tree by accessible name and/or role.
+    #
+    # @param [String, nil] name
+    # @param [String, nil] role
+    # @param [Ferrum::Node, nil] node  Scope the query to this node's subtree.
+    # @return [Array<AXNode>]
+    #
+    def query(name: nil, role: nil, node: nil)
+      page = node ? node.page : @page
+      params = { accessibleName: name, role: role }.compact
+      params[:nodeId] = node ? node.node_id : page.document_node_id
+      build(page.command("Accessibility.queryAXTree", **params)["nodes"])
+    end
+
+    #
+    # The root AXNode of the (optionally framed) document.
+    #
+    # @param [String, nil] frame_id
+    # @return [AXNode, nil]
+    #
+    def root(frame_id: nil)
+      params = { depth: 1, frameId: frame_id }.compact
+      build(@page.command("Accessibility.getFullAXTree", **params)["nodes"]).first
+    end
+
+    # @return [self]
+    def enable
+      @page.command("Accessibility.enable")
+      self
+    end
+
+    # @return [self]
+    def disable
+      @page.command("Accessibility.disable")
+      self
+    end
+
+    private
+
+    def build(nodes)
+      Array(nodes).map { |node| AXNode.new(node) }
+    end
+  end
+end

lib/ferrum/accessibility/ax_node.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Ferrum
+  class Accessibility
+    #
+    # Represents an [AXNode](https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/#type-AXNode)
+    # from the CDP Accessibility domain.
+    #
+    class AXNode
+      #
+      # @param [Hash{String => Object}] params
+      #   The parsed CDP AXNode attributes.
+      #
+      def initialize(params)
+        @params = deep_freeze(params)
+      end
+
+      # @return [String, nil]
+      def role
+        @params.dig("role", "value")
+      end
+
+      # @return [String, nil]
+      def name
+        @params.dig("name", "value")
+      end
+
+      # @return [String, nil]
+      def description
+        @params.dig("description", "value")
+      end
+
+      # @return [String, Numeric, Boolean, nil] raw CDP AXValue.value; type varies by control
+      def value
+        @params.dig("value", "value")
+      end
+
+      # @return [Hash{String => Object}]
+      #   ARIA/computed properties flattened to `name => value`.
+      def properties
+        @properties ||= Array(@params["properties"]).to_h do |property|
+          [property["name"], property.dig("value", "value")]
+        end.freeze
+      end
+
+      # @return [Boolean]
+      def ignored?
+        @params["ignored"] == true
+      end
+
+      # @return [Array, nil]
+      def ignored_reasons
+        @params["ignoredReasons"]
+      end
+
+      # @return [String, nil]
+      def node_id
+        @params["nodeId"]
+      end
+
+      # @return [Integer, nil]
+      def backend_dom_node_id
+        @params["backendDOMNodeId"]
+      end
+
+      # @return [Array, nil]
+      def child_ids
+        @params["childIds"]
+      end
+
+      # @return [Hash]
+      #   The raw CDP AXNode hash.
+      def to_h
+        @params
+      end
+
+      private
+
+      def deep_freeze(object)
+        case object
+        when Hash  then object.each { |key, value| deep_freeze(key.freeze) && deep_freeze(value) }
+        when Array then object.each { |value| deep_freeze(value) }
+        end
+        object.freeze
+      end
+    end
+  end
+end

lib/ferrum/browser.rb

@@ -21,7 +21,7 @@ class Browser
     delegate %i[go_to goto go back forward refresh reload stop wait_for_reload
                 at_css at_xpath css xpath current_url current_title url title
                 body doctype content=
-                headers cookies network downloads
+                headers cookies network accessibility downloads
                 mouse keyboard
                 screenshot pdf mhtml viewport_size device_pixel_ratio
                 start_screencast stop_screencast

lib/ferrum/node.rb

@@ -229,6 +229,14 @@ def computed_style
         .each_with_object({}) { |style, memo| memo.merge!(style["name"] => style["value"]) }
     end
 
+    # Returns the computed accessibility node for the element, or nil if the
+    # element is ignored by the accessibility tree.
+    #
+    # @return [Accessibility::AXNode, nil]
+    def axnode
+      page.accessibility.node_for(self)
+    end
+
     def remove
       page.command("DOM.removeNode", nodeId: node_id)
     end

lib/ferrum/page.rb

@@ -8,6 +8,7 @@
 require "ferrum/cookies"
 require "ferrum/dialog"
 require "ferrum/network"
+require "ferrum/accessibility"
 require "ferrum/downloads"
 require "ferrum/page/frames"
 require "ferrum/page/screencast"
@@ -57,6 +58,11 @@ class Page
     # @return [Network]
     attr_reader :network
 
+    # Accessibility object.
+    #
+    # @return [Accessibility]
+    attr_reader :accessibility
+
     # Headers object.
     #
     # @return [Headers]
@@ -88,6 +94,7 @@ def initialize(client, context_id:, target_id:, proxy: nil)
       @headers = Headers.new(self)
       @cookies = Cookies.new(self)
       @network = Network.new(self)
+      @accessibility = Accessibility.new(self)
       @tracing = Tracing.new(self)
       @downloads = Downloads.new(self)
 

sig/ferrum/accessibility.rbs

@@ -0,0 +1,25 @@
+module Ferrum
+  class Accessibility
+    @page: Page
+
+    def initialize: (Page page) -> void
+
+    def node_for: (Node node) -> AXNode?
+
+    def partial_tree: (node: Node, ?fetch_relatives: bool) -> Array[AXNode]
+
+    def snapshot: (?depth: Integer?, ?frame_id: String?) -> Array[AXNode]
+
+    def query: (?name: String?, ?role: String?, ?node: Node?) -> Array[AXNode]
+
+    def root: (?frame_id: String?) -> AXNode?
+
+    def enable: () -> self
+
+    def disable: () -> self
+
+    private
+
+    def build: (Array[untyped]? nodes) -> Array[AXNode]
+  end
+end

sig/ferrum/accessibility/ax_node.rbs

@@ -0,0 +1,31 @@
+module Ferrum
+  class Accessibility
+    class AXNode
+      @params: Hash[String, untyped]
+
+      def initialize: (Hash[String, untyped] params) -> void
+
+      def role: () -> String?
+
+      def name: () -> String?
+
+      def description: () -> String?
+
+      def value: () -> (String | Numeric | bool | nil)
+
+      def properties: () -> Hash[String, untyped]
+
+      def ignored?: () -> bool
+
+      def ignored_reasons: () -> Array[untyped]?
+
+      def node_id: () -> String?
+
+      def backend_dom_node_id: () -> Integer?
+
+      def child_ids: () -> Array[String]?
+
+      def to_h: () -> Hash[String, untyped]
+    end
+  end
+end

sig/ferrum/node.rbs

@@ -77,6 +77,8 @@ module Ferrum
 
     def computed_style: () -> untyped
 
+    def axnode: () -> Accessibility::AXNode?
+
     private
 
     def bounding_rect_coordinates: () -> untyped

sig/ferrum/page.rbs

@@ -18,6 +18,7 @@ module Ferrum
     attr_reader mouse: Mouse
     attr_reader keyboard: Keyboard
     attr_reader network: Network
+    attr_reader accessibility: Accessibility
     attr_reader headers: Headers
     attr_reader cookies: Cookies
     attr_reader downloads: Downloads