ferrum 0.17.1 → 0.18.0

data/lib/ferrum/accessibility/ax_node.rb

@@ -0,0 +1,108 @@
+# 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
+
+      # The AX node's role, e.g. `"button"`.
+      #
+      # @return [String, nil]
+      def role
+        @params.dig("role", "value")
+      end
+
+      # The AX node's accessible name.
+      #
+      # @return [String, nil]
+      def name
+        @params.dig("name", "value")
+      end
+
+      # The AX node's accessible description.
+      #
+      # @return [String, nil]
+      def description
+        @params.dig("description", "value")
+      end
+
+      # The AX node's current value.
+      #
+      # @return [String, Numeric, Boolean, nil] raw CDP AXValue.value; type varies by control
+      def value
+        @params.dig("value", "value")
+      end
+
+      # ARIA/computed properties flattened to `name => value`.
+      #
+      # @return [Hash{String => Object}]
+      def properties
+        @properties ||= Array(@params["properties"]).to_h do |property|
+          [property["name"], property.dig("value", "value")]
+        end.freeze
+      end
+
+      # Whether the node is ignored by the accessibility tree.
+      #
+      # @return [Boolean]
+      def ignored?
+        @params["ignored"] == true
+      end
+
+      # The reasons the node is ignored, if any.
+      #
+      # @return [Array, nil]
+      def ignored_reasons
+        @params["ignoredReasons"]
+      end
+
+      # The AX node's id.
+      #
+      # @return [String, nil]
+      def node_id
+        @params["nodeId"]
+      end
+
+      # The id of the DOM node this AX node is backed by.
+      #
+      # @return [Integer, nil]
+      def backend_dom_node_id
+        @params["backendDOMNodeId"]
+      end
+
+      # The ids of this AX node's children.
+      #
+      # @return [Array, nil]
+      def child_ids
+        @params["childIds"]
+      end
+
+      # The raw CDP AXNode hash.
+      #
+      # @return [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

data/lib/ferrum/accessibility.rb

@@ -0,0 +1,106 @@
+# 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
+
+    # Enables the Accessibility domain, activating live AX tree change events.
+    #
+    # @return [self]
+    def enable
+      @page.command("Accessibility.enable")
+      self
+    end
+
+    # Disables the Accessibility domain.
+    #
+    # @return [self]
+    def disable
+      @page.command("Accessibility.disable")
+      self
+    end
+
+    private
+
+    def build(nodes)
+      Array(nodes).map { |node| AXNode.new(node) }
+    end
+  end
+end

data/lib/ferrum/browser/binary.rb

@@ -2,23 +2,64 @@
 
 module Ferrum
   class Browser
+    #
+    # Locates an executable on the system `PATH`, mirroring what a shell's
+    # `which`/`where` would find. Used to resolve the browser (and Xvfb)
+    # binary when no explicit path is configured.
+    #
     module Binary
       module_function
 
+      #
+      # Finds the first executable path for the given command(s) on `PATH`.
+      #
+      # @param [String, Array<String>] commands
+      #   Command name(s) to look up.
+      #
+      # @return [String, nil]
+      #   Absolute path to the executable, or `nil` if none is found.
+      #
       def find(commands)
         enum(commands).first
       end
 
+      #
+      # Finds all executable paths for the given command(s) on `PATH`.
+      #
+      # @param [String, Array<String>] commands
+      #   Command name(s) to look up.
+      #
+      # @return [Array<String>]
+      #   Absolute paths to matching executables.
+      #
       def all(commands)
         enum(commands).force
       end
 
+      #
+      # Lazily enumerates executable paths for the given command(s) on `PATH`.
+      #
+      # @param [String, Array<String>] commands
+      #   Command name(s) to look up.
+      #
+      # @return [Enumerator::Lazy]
+      #   Lazy enumerator yielding matching executable paths.
+      #
       def enum(commands)
         paths, exts = prepare_paths
         cmds = Array(commands).product(paths, exts)
         lazy_find(cmds)
       end
 
+      #
+      # Directories on `PATH` and the executable extensions to try against them.
+      #
+      # @return [Array(Array<String>, Array<String>)]
+      #   The `PATH` directories, and the extensions from `PATHEXT` (plus `""`).
+      #
+      # @raise [EmptyPathError]
+      #   If `PATH` is empty.
+      #
       def prepare_paths
         exts = (ENV.key?("PATHEXT") ? ENV.fetch("PATHEXT").split(";") : []) << ""
         paths = ENV["PATH"].split(File::PATH_SEPARATOR)

data/lib/ferrum/browser/command.rb

@@ -2,6 +2,12 @@
 
 module Ferrum
   class Browser
+    #
+    # Builds the OS-level command used to spawn the browser process: resolves
+    # the executable path and merges the browser-specific required/default
+    # flags (see {Options::Base}) with any user-supplied ones into a single
+    # argument list.
+    #
     class Command
       NOT_FOUND = "Could not find an executable for the browser. Try to make " \
                   "it available on the PATH or set environment variable for " \
@@ -35,14 +41,28 @@ module Ferrum
         merge_options
       end
 
+      # Whether the browser should be launched under Xvfb.
+      #
+      # @return [Boolean]
       def xvfb?
         !!options.xvfb
       end
 
+      #
+      # Command line arguments for spawning the browser process.
+      #
+      # @return [Array<String>]
+      #   The browser path followed by its CLI flags.
+      #
       def to_a
         [path] + @flags.map { |k, v| v.nil? ? "--#{k}" : "--#{k}=#{v}" }
       end
 
+      #
+      # String representation of the command used to spawn the browser process.
+      #
+      # @return [String]
+      #
       def to_s
         to_a.join(" \\ \n  ")
       end

data/lib/ferrum/browser/options/base.rb

@@ -6,14 +6,30 @@ require "open3"
 module Ferrum
   class Browser
     class Options
+      #
+      # Abstract base for browser-specific default option builders. Subclasses
+      # (e.g. {Options::Chrome}, {Options::Firefox}) declare their own
+      # `DEFAULT_OPTIONS` and `PLATFORM_PATH` constants and implement
+      # {#merge_required}/{#merge_default} to produce the final CLI flags used
+      # by {Command}.
+      #
       class Base
         include Singleton
 
+        #
+        # Singleton instance holding the browser's default options.
+        #
+        # @return [Base]
+        #
         def self.options
           instance
         end
 
+        # The installed browser's version string, obtained by running its
+        # binary with `--version`.
+        #
         # @return [String, nil]
+        #   The version output, or `nil` if the binary can't be found/run.
         def self.version
           out, = Open3.capture2(instance.detect_path, "--version")
           out.strip
@@ -21,22 +37,73 @@ module Ferrum
           nil
         end
 
+        #
+        # Default CLI flags for the browser.
+        #
+        # @return [Hash{String => Object}]
+        #
         def to_h
           self.class::DEFAULT_OPTIONS
         end
 
+        #
+        # Default CLI flags excluding the given keys.
+        #
+        # @param [Array<String>] keys
+        #   Flag names to exclude.
+        #
+        # @return [Hash{String => Object}]
+        #
         def except(*keys)
-          to_h.reject { |n, _| keys.include?(n) }
+          to_h.except(*keys)
         end
 
+        #
+        # Locates the browser executable on the system.
+        #
+        # @return [String, nil]
+        #   Absolute path to the browser binary, or `nil` if not found.
+        #
         def detect_path
-          Binary.find(self.class::PLATFORM_PATH[Utils::Platform.name])
+          Binary.find(self.class::PLATFORM_PATH[Utils::Platform.platform_name])
         end
 
+        #
+        # Merges the CLI flags that are always required to drive the browser
+        # over CDP (e.g. remote debugging port, user data dir) into `flags`.
+        # Abstract; overridden by {Options::Chrome}/{Options::Firefox}.
+        #
+        # @param [Hash{String => Object}] flags
+        #   The flags accumulated so far.
+        # @param [Options] options
+        #   The user-supplied browser options.
+        # @param [String] user_data_dir
+        #   Path to the browser's user data directory.
+        #
+        # @return [Hash{String => Object}]
+        #
+        # @raise [NotImplementedError]
+        #   Always, unless overridden by a subclass.
+        #
         def merge_required(flags, options, user_data_dir)
           raise NotImplementedError
         end
 
+        #
+        # Merges this browser's default CLI flags (see {#to_h}) into `flags`,
+        # unless `options.ignore_default_browser_options` is set. Abstract;
+        # overridden by {Options::Chrome}/{Options::Firefox}.
+        #
+        # @param [Hash{String => Object}] flags
+        #   The flags accumulated so far.
+        # @param [Options] options
+        #   The user-supplied browser options.
+        #
+        # @return [Hash{String => Object}]
+        #
+        # @raise [NotImplementedError]
+        #   Always, unless overridden by a subclass.
+        #
         def merge_default(flags, options)
           raise NotImplementedError
         end

data/lib/ferrum/browser/options/chrome.rb

@@ -3,46 +3,72 @@
 module Ferrum
   class Browser
     class Options
+      #
+      # Chrome/Chromium-specific default flags and binary locations. Provides
+      # the CLI flags required to drive Chrome over CDP as well as the
+      # hardened defaults (disabling background networking, extensions,
+      # infobars, etc.) applied unless the user opts out.
+      #
       class Chrome < Base
         DEFAULT_OPTIONS = {
-          "headless" => nil,
-          "hide-scrollbars" => nil,
-          "mute-audio" => nil,
-          "enable-automation" => nil,
-          "disable-web-security" => nil,
-          "disable-session-crashed-bubble" => nil,
-          "disable-breakpad" => nil,
-          "disable-sync" => nil,
-          "no-first-run" => nil,
-          "use-mock-keychain" => nil,
-          "keep-alive-for-test" => nil,
-          "disable-popup-blocking" => nil,
-          "disable-extensions" => nil,
-          "disable-component-extensions-with-background-pages" => nil,
-          "disable-hang-monitor" => nil,
-          "disable-features" => "site-per-process,IsolateOrigins,TranslateUI",
-          "disable-translate" => nil,
+          "allow-pre-commit-input" => nil,
           "disable-background-networking" => nil,
-          "enable-features" => "NetworkService,NetworkServiceInProcess",
           "disable-background-timer-throttling" => nil,
           "disable-backgrounding-occluded-windows" => nil,
+          "disable-blink-features" => "AutomationControlled",
+          "disable-breakpad" => nil,
           "disable-client-side-phishing-detection" => nil,
+          "disable-component-extensions-with-background-pages" => nil,
+          "disable-component-update" => nil,
+          "disable-crash-reporter" => nil,
           "disable-default-apps" => nil,
           "disable-dev-shm-usage" => nil,
+          "disable-extensions" => nil,
+          "disable-features" => %w[
+            site-per-process
+            IsolateOrigins
+            TranslateUI
+            Translate
+            MacAppCodeSignClone
+            InterestFeedContentSuggestion
+            OptimizationHints
+            AcceptCHFrame
+            MediaRouter
+          ].join(","),
+          "disable-field-trial-config" => nil,
+          "disable-hang-monitor" => nil,
+          "disable-infobars" => nil,
           "disable-ipc-flooding-protection" => nil,
+          "disable-popup-blocking" => nil,
           "disable-prompt-on-repost" => nil,
           "disable-renderer-backgrounding" => nil,
+          "disable-search-engine-choice-screen" => nil,
+          "disable-session-crashed-bubble" => nil,
           "disable-site-isolation-trials" => nil,
+          "disable-smooth-scrolling" => nil,
+          "disable-sync" => nil,
+          "disable-translate" => nil,
+          "disable-web-security" => nil,
+          "enable-automation" => nil,
+          "enable-features" => %w[
+            NetworkService
+            NetworkServiceInProcess
+          ].join(","),
           "force-color-profile" => "srgb",
+          "headless" => nil,
+          "hide-scrollbars" => nil,
+          "keep-alive-for-test" => nil,
           "metrics-recording-only" => nil,
-          "safebrowsing-disable-auto-update" => nil,
-          "password-store" => "basic",
+          "mute-audio" => nil,
+          "no-crash-upload" => nil,
+          "no-crashpad" => nil,
+          "no-default-browser-check" => nil,
+          "no-first-run" => nil,
           "no-startup-window" => nil,
+          "password-store" => "basic",
           "remote-allow-origins" => "*",
-          "disable-blink-features" => "AutomationControlled"
-          # NOTE: --no-sandbox is not needed if you properly set up a user in the container.
-          # https://github.com/ebidel/lighthouse-ci/blob/master/builder/Dockerfile#L35-L40
-          # "no-sandbox" => nil,
+          "safebrowsing-disable-auto-update" => nil,
+          "use-mock-keychain" => nil
         }.freeze
 
         MAC_BIN_PATH = [
@@ -61,6 +87,21 @@ module Ferrum
           linux: LINUX_BIN_PATH
         }.freeze
 
+        #
+        # Merges CLI flags required for Chrome to work with CDP.
+        #
+        # @param [Hash] flags
+        #   Flags to merge required ones into.
+        #
+        # @param [Ferrum::Browser::Options] options
+        #   Browser options.
+        #
+        # @param [String] user_data_dir
+        #   Path to the browser's user data directory.
+        #
+        # @return [Hash]
+        #   Merged flags.
+        #
         def merge_required(flags, options, user_data_dir)
           flags = flags.merge("remote-debugging-port" => options.port,
                               "remote-debugging-address" => options.host,
@@ -75,16 +116,37 @@ module Ferrum
           flags
         end
 
+        #
+        # Merges Chrome's default flags with the given ones, unless the browser
+        # is configured to ignore default browser options.
+        #
+        # @param [Hash] flags
+        #   Flags that take precedence over the defaults.
+        #
+        # @param [Ferrum::Browser::Options] options
+        #   Browser options.
+        #
+        # @return [Hash]
+        #   Merged flags.
+        #
         def merge_default(flags, options)
-          defaults = except("headless", "disable-gpu") if options.headless == false
-          defaults ||= DEFAULT_OPTIONS
+          defaults = options.headless == false ? except("headless", "disable-gpu") : DEFAULT_OPTIONS.dup
           defaults.delete("no-startup-window") if options.incognito == false
+
+          if options.dockerize || ENV["FERRUM_CHROME_DOCKERIZE"] == "true"
+            # NOTE: --no-sandbox is not needed if you properly set up a user in the container.
+            # https://github.com/ebidel/lighthouse-ci/blob/master/builder/Dockerfile#L35-L40
+            defaults = defaults.merge("no-sandbox" => nil, "disable-setuid-sandbox" => nil)
+          end
+
           # On Windows, the --disable-gpu flag is a temporary workaround for a few bugs.
           # See https://bugs.chromium.org/p/chromium/issues/detail?id=737678 for more information.
           defaults = defaults.merge("disable-gpu" => nil) if Utils::Platform.windows?
+
           # Use Metal on Apple Silicon
           # https://github.com/google/angle#platform-support-via-backing-renderers
           defaults = defaults.merge("use-angle" => "metal") if Utils::Platform.mac_arm?
+
           defaults.merge(flags)
         end
       end

data/lib/ferrum/browser/options/firefox.rb

@@ -3,6 +3,11 @@
 module Ferrum
   class Browser
     class Options
+      #
+      # Firefox-specific default flags and binary locations. Provides the CLI
+      # flags required to drive Firefox over CDP (remote debugger address and
+      # profile directory) along with its (minimal) set of default flags.
+      #
       class Firefox < Base
         DEFAULT_OPTIONS = {
           "headless" => nil
@@ -22,10 +27,37 @@ module Ferrum
           linux: LINUX_BIN_PATH
         }.freeze
 
+        #
+        # Merges CLI flags required for Firefox to work with CDP.
+        #
+        # @param [Hash] flags
+        #   Flags to merge required ones into.
+        #
+        # @param [Ferrum::Browser::Options] options
+        #   Browser options.
+        #
+        # @param [String] user_data_dir
+        #   Path to the browser's profile directory.
+        #
+        # @return [Hash]
+        #   Merged flags.
+        #
         def merge_required(flags, options, user_data_dir)
           flags.merge("remote-debugger" => "#{options.host}:#{options.port}", "profile" => user_data_dir)
         end
 
+        #
+        # Merges Firefox's default flags with the given ones.
+        #
+        # @param [Hash] flags
+        #   Flags that take precedence over the defaults.
+        #
+        # @param [Ferrum::Browser::Options] options
+        #   Browser options.
+        #
+        # @return [Hash]
+        #   Merged flags.
+        #
         def merge_default(flags, options)
           defaults = except("headless") unless options.headless