ferrum 0.17.1 → 0.18.0

data/lib/ferrum/node.rb

@@ -1,36 +1,92 @@
 # frozen_string_literal: true
 
 module Ferrum
+  #
+  # Represents a DOM node (an element or a text node) found on a {Page} or
+  # within a {Frame}. Provides methods to inspect it (`text`, `property`,
+  # `attribute`), interact with it (`click`, `focus`, `type`, `select`) and
+  # search within it (`at_css`, `at_xpath`, `css`, `xpath`).
+  #
+  # @note Node identity is tied to the target it was found on; a `Node`
+  #   fetched before a navigation cannot be used afterwards.
+  #
   class Node
     MOVING_WAIT_DELAY = ENV.fetch("FERRUM_NODE_MOVING_WAIT", 0.01).to_f
     MOVING_WAIT_ATTEMPTS = ENV.fetch("FERRUM_NODE_MOVING_ATTEMPTS", 50).to_i
 
-    attr_reader :page, :target_id, :node_id, :description, :tag_name
+    attr_reader :page, :target_id, :description, :tag_name
 
-    def initialize(frame, target_id, node_id, description)
+    def initialize(frame, target_id, description, object_id: nil, node_id: nil)
       @page = frame.page
       @target_id = target_id
-      @node_id = node_id
       @description = description
       @tag_name = description["nodeName"].downcase
+      @object_id = object_id
+      @node_id = node_id
+    end
+
+    # Frontend node id is resolved lazily, on first actual need (focus, click, scroll_into_view, etc.)
+    # We can try to subscribe to `DOM.childNodeRemoved` and `DOM.childNodeInserted` in the future
+    # to keep track of nodes.
+    def node_id
+      @node_id ||= begin
+        id = page.command("DOM.requestNode", objectId: @object_id)["nodeId"]
+        raise NodeNotFoundError, "node is not trackable" if id.zero?
+
+        id
+      rescue NoExecutionContextError
+        raise NodeNotFoundError, "node is not trackable"
+      end
     end
 
+    # Whether this is an element node, as opposed to e.g. a text node.
+    #
+    # @return [Boolean]
     def node?
       description["nodeType"] == 1 # nodeType: 3, nodeName: "#text" e.g.
     end
 
+    #
+    # The id of the frame this node belongs to.
+    #
+    # @return [String]
+    #
     def frame_id
       description["frameId"]
     end
 
+    #
+    # The {Frame} this node belongs to. Keep using finder methods (`at_css`,
+    # `at_xpath`, etc.) on it to search within that frame, e.g. inside an
+    # `iframe`.
+    #
+    # @return [Frame, nil]
+    #
+    # @example
+    #   frame = page.at_xpath("//iframe").frame # => Frame
+    #   frame.at_css("//a[text() = 'Log in']") # => Node
+    #
     def frame
       page.frame_by(id: frame_id)
     end
 
+    #
+    # Focuses the node.
+    #
+    # @return [self]
+    #
+    # @example
+    #   input = page.at_css("input[name='q']")
+    #   input.focus
+    #
     def focus
       tap { page.command("DOM.focus", slowmoable: true, nodeId: node_id) }
     end
 
+    # Whether the node can receive focus. Attempts to {#focus} the node to
+    # find out.
+    #
+    # @return [Boolean]
     def focusable?
       focus
       true
@@ -38,6 +94,20 @@ module Ferrum
       e.message == "Element is not focusable" ? false : raise
     end
 
+    #
+    # Waits until the node's position stops changing, retrying up to
+    # `attempts` times. Raises {NodeMovingError} if the node is still moving
+    # after the last attempt.
+    #
+    # @param [Float] delay
+    #   Seconds to wait between two position checks.
+    #
+    # @param [Integer] attempts
+    #   Maximum number of attempts before raising.
+    #
+    # @return [Array]
+    #   The content quads of the node once it has stopped moving.
+    #
     def wait_for_stop_moving(delay: MOVING_WAIT_DELAY, attempts: MOVING_WAIT_ATTEMPTS)
       Utils::Attempt.with_retry(errors: NodeMovingError, max: attempts, wait: 0) do
         previous, current = content_quads_with(delay: delay)
@@ -47,15 +117,39 @@ module Ferrum
       end
     end
 
+    # Checks whether the node's position has stopped changing, by comparing
+    # two content-quad snapshots taken `delay` seconds apart.
+    #
+    # @param [Float] delay
+    #   Seconds to wait between the two position checks.
+    #
+    # @return [Boolean]
     def moving?(delay: MOVING_WAIT_DELAY)
       previous, current = content_quads_with(delay: delay)
       previous == current
     end
 
+    #
+    # Removes focus from the node.
+    #
+    # @return [self]
+    #
     def blur
       tap { evaluate("this.blur()") }
     end
 
+    #
+    # Sends keystrokes to the currently focused element via the page's
+    # keyboard. Typically chained after {#focus} or `click`.
+    #
+    # @param [Array<String, Symbol, (Symbol, String)>] keys
+    #   The keys to type, e.g. `"Input"`, `[:Shift, "s"], "tring"`.
+    #
+    # @return [self]
+    #
+    # @example
+    #   input.focus.type("Input")
+    #
     def type(*keys)
       tap { page.keyboard.type(*keys) }
     end
@@ -67,32 +161,46 @@ module Ferrum
       x, y = find_position(**offset)
       modifiers = page.keyboard.modifiers(keys)
 
+      # `:right` and `:double` pass `wait: 0` to preserve the historical
+      # no-network-wait default of `Mouse#up` and `Mouse#down`
       case mode
       when :right
-        page.mouse.move(x: x, y: y)
-        page.mouse.down(button: :right, modifiers: modifiers)
-        sleep(delay)
-        page.mouse.up(button: :right, modifiers: modifiers)
+        page.mouse.click(x:, y:, modifiers:, delay:, button: :right, wait: 0)
       when :double
-        page.mouse.move(x: x, y: y)
-        page.mouse.down(modifiers: modifiers, count: 2)
-        sleep(delay)
-        page.mouse.up(modifiers: modifiers, count: 2)
+        page.mouse.click(x:, y:, modifiers:, delay:, count: 2, wait: 0)
       when :left
-        page.mouse.click(x: x, y: y, modifiers: modifiers, delay: delay)
+        page.mouse.click(x:, y:, modifiers:, delay:)
       end
 
       self
     end
 
+    # Not currently implemented.
+    #
+    # @raise [NotImplementedError] always
     def hover
       raise NotImplementedError
     end
 
+    #
+    # Scrolls the node into view if it is not already visible.
+    #
+    # @return [self]
+    #
+    # @example
+    #   page.at_css("#footer").scroll_into_view
+    #
     def scroll_into_view
       tap { page.command("DOM.scrollIntoViewIfNeeded", nodeId: node_id) }
     end
 
+    # Whether the node's bounding rect is fully within the viewport (or,
+    # when `of:` is given, within that scoping element's bounds).
+    #
+    # @param [Node, nil] of
+    #   An element to use as the visible bounds instead of the window.
+    #
+    # @return [Boolean]
     def in_viewport?(of: nil)
       function = <<~JS
         function(element, scope) {
@@ -109,26 +217,94 @@ module Ferrum
       page.evaluate_func(function, self, of)
     end
 
+    #
+    # Sets files on a file input node.
+    #
+    # @param [String, Array<String>] value
+    #   Path or paths to the file(s) to upload.
+    #
+    # @return [Hash{String => Object}]
+    #
+    # @example
+    #   page.at_css("input[type=file]").select_file("/path/to/file.png")
+    #
     def select_file(value)
-      page.command("DOM.setFileInputFiles", slowmoable: true, nodeId: node_id, files: Array(value))
-    end
-
+      page.command(
+        "DOM.setFileInputFiles",
+        slowmoable: true,
+        backendNodeId: description["backendNodeId"],
+        files: Array(value)
+      )
+    end
+
+    #
+    # Finds a node by xpath, scoped to search within this node. Runs
+    # `document.evaluate` within this node.
+    #
+    # @param [String] selector
+    #
+    # @return [Node, nil]
+    #
+    # @example
+    #   page.at_xpath("//iframe").at_xpath(".//a") # => Node
+    #
     def at_xpath(selector)
       page.at_xpath(selector, within: self)
     end
 
+    #
+    # Finds a node by CSS selector, scoped to search within this node. Runs
+    # `querySelector` within this node.
+    #
+    # @param [String] selector
+    #
+    # @return [Node, nil]
+    #
+    # @example
+    #   page.at_css("form").at_css("input[name='q']") # => Node
+    #
     def at_css(selector)
       page.at_css(selector, within: self)
     end
 
+    #
+    # Finds nodes by xpath, scoped to search within this node. Runs
+    # `document.evaluate` within this node.
+    #
+    # @param [String] selector
+    #
+    # @return [Array<Node>]
+    #
+    # @example
+    #   page.at_css("ul").xpath(".//li") # => [Node]
+    #
     def xpath(selector)
       page.xpath(selector, within: self)
     end
 
+    #
+    # Finds nodes by CSS selector, scoped to search within this node. Runs
+    # `querySelectorAll` within this node.
+    #
+    # @param [String] selector
+    #
+    # @return [Array<Node>]
+    #
+    # @example
+    #   page.at_css("ul").css("li") # => [Node]
+    #
     def css(selector)
       page.css(selector, within: self)
     end
 
+    #
+    # The node's text content, i.e. `textContent`.
+    #
+    # @return [String]
+    #
+    # @example
+    #   page.at_css("a > h3").text # => "rubycdp/ferrum: Ruby Chrome/Chromium driver - GitHub"
+    #
     def text
       evaluate("this.textContent")
     end
@@ -138,19 +314,52 @@ module Ferrum
       evaluate("this.innerText")
     end
 
+    #
+    # The node's `value` property. Useful for form elements such as `input`,
+    # `select` and `textarea`.
+    #
+    # @return [Object]
+    #
     def value
       evaluate("this.value")
     end
 
+    #
+    # Returns the given JavaScript property of the node.
+    #
+    # @param [String] name
+    #
+    # @return [Object]
+    #
+    # @example
+    #   page.at_css("input").property("value") # => "Foo"
+    #
     def property(name)
       evaluate("this['#{name}']")
     end
     alias [] property
 
+    #
+    # Returns the value of the given HTML attribute, i.e.
+    # `getAttribute(name)`. Unlike {#property}, it reads the attribute as
+    # defined in markup rather than the live DOM property.
+    #
+    # @param [String] name
+    #
+    # @return [String, nil]
+    #
+    # @example
+    #   page.at_css("input").attribute("value") # => "Foo"
+    #
     def attribute(name)
       evaluate("this.getAttribute('#{name}')")
     end
 
+    #
+    # Returns the selected `option` nodes of a `select` element.
+    #
+    # @return [Array<Node>]
+    #
     def selected
       function = <<~JS
         function(element) {
@@ -163,6 +372,29 @@ module Ferrum
       page.evaluate_func(function, self, on: self)
     end
 
+    #
+    # (chainable) Selects options of a `select` element by the given
+    # attribute.
+    #
+    # @param [Array<String>] values
+    #   The value(s) to select. Accepts a string, multiple strings, or an
+    #   array of strings.
+    #
+    # @param [Symbol] by
+    #   The `option` attribute to match `values` against, e.g. `:value` or
+    #   `:text`.
+    #
+    # @return [self]
+    #
+    # @example
+    #   page.at_xpath("//*[select]").select(["1"]) # => Node (select)
+    #   page.at_xpath("//*[select]").select(["text"], by: :text) # => Node (select)
+    #
+    # @example Accepts a string, multiple strings or an array of strings:
+    #   page.at_xpath("//*[select]").select("1")
+    #   page.at_xpath("//*[select]").select("1", "2")
+    #   page.at_xpath("//*[select]").select(["1", "2"])
+    #
     def select(*values, by: :value)
       tap do
         function = <<~JS
@@ -184,10 +416,29 @@ module Ferrum
       end
     end
 
+    #
+    # Evaluates the given JavaScript expression with `this` bound to the
+    # node.
+    #
+    # @param [String] expression
+    #
+    # @return [Object]
+    #
+    # @example
+    #   page.at_css("input").evaluate("this.value")
+    #
     def evaluate(expression)
       page.evaluate_on(node: self, expression: expression)
     end
 
+    #
+    # Two nodes are equal when they belong to the same target and share the
+    # same backend node id.
+    #
+    # @param [Object] other
+    #
+    # @return [Boolean]
+    #
     def ==(other)
       return false unless other.is_a?(Node)
 
@@ -197,10 +448,30 @@ module Ferrum
       target_id == other.target_id && description["backendNodeId"] == other.description["backendNodeId"]
     end
 
+    #
+    # A developer-friendly string representation of the node.
+    #
+    # @return [String]
+    #
     def inspect
       %(#<#{self.class} @target_id=#{@target_id.inspect} @node_id=#{@node_id} @description=#{@description.inspect}>)
     end
 
+    #
+    # Finds the x, y coordinates to click or hover on the node.
+    #
+    # @param [Integer, nil] x
+    #   Horizontal offset from the reference point.
+    #
+    # @param [Integer, nil] y
+    #   Vertical offset from the reference point.
+    #
+    # @param [Symbol] position
+    #   `:top` to offset from the node's top-left corner, `:center` to offset
+    #   from its center.
+    #
+    # @return [(Integer, Integer)]
+    #
     def find_position(x: nil, y: nil, position: :top)
       points = wait_for_stop_moving.map { |q| to_points(q) }.first
       get_position(points, x, y, position)
@@ -218,10 +489,29 @@ module Ferrum
         .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
+
+    #
+    # Removes the node from the DOM.
+    #
+    # @return [Hash{String => Object}]
+    #
+    # @example
+    #   page.at_css("#ad").remove
+    #
     def remove
       page.command("DOM.removeNode", nodeId: node_id)
     end
 
+    # Whether the node still exists in the DOM.
+    #
+    # @return [Boolean]
     def exists?
       page.command("DOM.resolveNode", nodeId: node_id)
       true

data/lib/ferrum/page/animation.rb

@@ -2,11 +2,16 @@
 
 module Ferrum
   class Page
+    #
+    # Controls the playback of CSS animations on the page via the CDP
+    # [Animation](https://chromedevtools.github.io/devtools-protocol/tot/Animation/)
+    # domain, allowing animations to be sped up, slowed down, or paused.
+    #
     module Animation
       #
       # Returns playback rate for CSS animations, defaults to `1`.
       #
-      # @return [Integer]
+      # @return [Number]
       #
       def playback_rate
         command("Animation.getPlaybackRate")["playbackRate"]
@@ -15,7 +20,7 @@ module Ferrum
       #
       # Sets playback rate of CSS animations.
       #
-      # @param [Integer] value
+      # @param [Number] value
       #
       # @example
       #   browser = Ferrum::Browser.new

data/lib/ferrum/page/frames.rb

@@ -4,6 +4,12 @@ require "ferrum/frame"
 
 module Ferrum
   class Page
+    #
+    # Tracks the page's frame tree and keeps it in sync with the browser by
+    # subscribing to the relevant `Page.*`, `Network.*`, and `Runtime.*` CDP
+    # events. Exposes lookups over the tracked {Frame} objects and reports
+    # when the tree has settled into an idle state.
+    #
     module Frames
       # The page's main frame, the top of the tree and the parent of all frames.
       #
@@ -63,12 +69,16 @@ module Ferrum
         end
       end
 
+      private
+
       def frames_subscribe
         subscribe_frame_attached
         subscribe_frame_detached
+        subscribe_frame_started_navigating
         subscribe_frame_started_loading
         subscribe_frame_navigated
         subscribe_frame_stopped_loading
+        subscribe_frame_lifecycle_events
 
         subscribe_navigated_within_document
 
@@ -79,8 +89,6 @@ module Ferrum
         subscribe_execution_contexts_cleared
       end
 
-      private
-
       def subscribe_frame_attached
         on("Page.frameAttached") do |params|
           parent_frame_id, frame_id = params.values_at("parentFrameId", "frameId")
@@ -100,6 +108,18 @@ module Ferrum
         end
       end
 
+      # Tracks the +loaderId+ for each navigating frame and clears stale
+      # lifecycle events from the previous navigation.
+      def subscribe_frame_started_navigating
+        on("Page.frameStartedNavigating") do |params|
+          frame = @frames[params["frameId"]]
+          if frame
+            frame.loader_id = params["loaderId"]
+            frame.lifecycle_events.clear
+          end
+        end
+      end
+
       def subscribe_frame_started_loading
         on("Page.frameStartedLoading") do |params|
           frame = @frames[params["frameId"]]
@@ -138,6 +158,33 @@ module Ferrum
         end
       end
 
+      # Appends +Page.lifecycleEvent+ events to {Frame#lifecycle_events}.
+      # Events from a superseded navigation (+loaderId+ mismatch) are dropped.
+      # Transitions +loading="lazy"+ iframes that Chrome never starts loading
+      # to +:stopped_loading+ on +networkIdle+, preventing a {Page#go_to} timeout.
+      def subscribe_frame_lifecycle_events
+        on("Page.lifecycleEvent") do |params|
+          frame = @frames[params["frameId"]]
+          next unless frame
+
+          frame.loader_id = params["loaderId"] unless frame.loader_id
+          # Reject stale events from a superseded navigation, iframes are not destroyed by Chrome, instead it creates
+          # new ones. Main frame stays with the same id, but new events start to flow in.
+          next if frame.loader_id != params["loaderId"]
+
+          event = params.slice("name", "timestamp")
+          frame.lifecycle_events << event
+
+          # This handles iframes with loading="lazy", those that Chrome attaches but parks outside the viewport.
+          # They do not trigger any events except `Page.frameAttached` and lifecycle events like:
+          # `init` and `networkIdle`. Without it `go_to` would wait for such iframe until it raises timeout.
+          if event["name"] == "networkIdle" && !frame.main?
+            frame.state = :stopped_loading
+            @event.set if idling?
+          end
+        end
+      end
+
       def subscribe_navigated_within_document
         on("Page.navigatedWithinDocument") do
           @event.set if idling?
@@ -177,21 +224,36 @@ module Ferrum
           execution_id = params["executionContextId"]
           frame = frame_by(execution_id: execution_id)
           frame&.execution_id = nil
-          frame&.state = :stopped_loading
+          frame&.state = :canceled
         end
       end
 
+      # On full navigations/reloads Chrome fires +Page.frameAttached+ with new
+      # frame IDs but skips +Page.frameDetached+ for old ones. Removing stale
+      # child frames here prevents them from blocking {#idling?} indefinitely.
+      # The main frame is reset in-place; child frames are re-added via
+      # +Page.frameAttached+.
       def subscribe_execution_contexts_cleared
         on("Runtime.executionContextsCleared") do
-          @frames.each_value do |f|
-            f.execution_id = nil
-            f.state = :stopped_loading
+          children = []
+
+          @frames.each do |frame_id, f|
+            if f.main?
+              f.execution_id = nil
+              f.loader_id = nil
+              f.lifecycle_events.clear
+              f.state = :canceled
+            else
+              children << frame_id
+            end
           end
+
+          children.each { |id| @frames.delete(id) }
         end
       end
 
       def idling?
-        @frames.values.all? { |f| f.state == :stopped_loading }
+        @frames.values.all?(&:idle?)
       end
     end
   end

data/lib/ferrum/page/screencast.rb

@@ -2,6 +2,11 @@
 
 module Ferrum
   class Page
+    #
+    # Starts and stops a live screencast of the page, streaming a sequence
+    # of frame images (a video-like feed) to a given block as the page
+    # renders.
+    #
     module Screencast
       # Starts sending frames to record screencast to the given block.
       #