RubyGems - ferrum - Versions diffs - 0.12 → 0.14 - Mend

ferrum 0.12 → 0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

checksums.yaml +4 -4
data/README.md +28 -22
data/lib/ferrum/browser/client.rb +6 -5
data/lib/ferrum/browser/command.rb +9 -6
data/lib/ferrum/browser/options/base.rb +1 -4
data/lib/ferrum/browser/options/chrome.rb +22 -10
data/lib/ferrum/browser/options/firefox.rb +3 -6
data/lib/ferrum/browser/options.rb +84 -0
data/lib/ferrum/browser/process.rb +6 -7
data/lib/ferrum/browser/version_info.rb +71 -0
data/lib/ferrum/browser/web_socket.rb +1 -1
data/lib/ferrum/browser/xvfb.rb +1 -1
data/lib/ferrum/browser.rb +184 -64
data/lib/ferrum/context.rb +3 -2
data/lib/ferrum/contexts.rb +2 -2
data/lib/ferrum/cookies/cookie.rb +183 -0
data/lib/ferrum/cookies.rb +122 -49
data/lib/ferrum/dialog.rb +30 -0
data/lib/ferrum/frame/dom.rb +177 -0
data/lib/ferrum/frame/runtime.rb +41 -61
data/lib/ferrum/frame.rb +91 -3
data/lib/ferrum/headers.rb +28 -0
data/lib/ferrum/keyboard.rb +45 -2
data/lib/ferrum/mouse.rb +84 -0
data/lib/ferrum/network/exchange.rb +104 -5
data/lib/ferrum/network/intercepted_request.rb +3 -12
data/lib/ferrum/network/request.rb +58 -19
data/lib/ferrum/network/request_params.rb +57 -0
data/lib/ferrum/network/response.rb +106 -4
data/lib/ferrum/network.rb +193 -8
data/lib/ferrum/node.rb +21 -1
data/lib/ferrum/page/animation.rb +16 -0
data/lib/ferrum/page/frames.rb +66 -11
data/lib/ferrum/page/screenshot.rb +97 -0
data/lib/ferrum/page/tracing.rb +26 -0
data/lib/ferrum/page.rb +158 -45
data/lib/ferrum/proxy.rb +91 -2
data/lib/ferrum/target.rb +6 -4
data/lib/ferrum/version.rb +1 -1
metadata +7 -101

data/lib/ferrum/frame.rb CHANGED Viewed

@@ -14,8 +14,30 @@ module Ferrum
       stopped_loading
     ].freeze
-    attr_accessor :id, :name
-    attr_reader :page, :parent_id, :state
+    # The Frame's unique id.
+    #
+    # @return [String]
+    attr_accessor :id
+    # If frame was given a name it should be here.
+    #
+    # @return [String, nil]
+    attr_accessor :name
+    # The page the frame belongs to.
+    #
+    # @return [Page]
+    attr_reader :page
+    # Parent frame id if this one is nested in another one.
+    #
+    # @return [String, nil]
+    attr_reader :parent_id
+    # One of the states frame's in.
+    #
+    # @return [:started_loading, :navigated, :stopped_loading, nil]
+    attr_reader :state
     def initialize(id, page, parent_id = nil)
       @id = id
@@ -30,18 +52,60 @@ module Ferrum
       @state = value
     end
+    #
+    # Returns current frame's `location.href`.
+    #
+    # @return [String]
+    #
+    # @example
+    #   browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+    #   frame = browser.frames[1]
+    #   frame.url # => https://interactive-examples.mdn.mozilla.net/pages/tabbed/iframe.html
+    #
     def url
       evaluate("document.location.href")
     end
+    #
+    # Returns current frame's title.
+    #
+    # @return [String]
+    #
+    # @example
+    #   browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+    #   frame = browser.frames[1]
+    #   frame.title # => HTML Demo: <iframe>
+    #
     def title
       evaluate("document.title")
     end
+    #
+    # If current frame is the main frame of the page (top of the tree).
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+    #   frame = browser.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
+    #   frame.main? # => false
+    #
     def main?
       @parent_id.nil?
     end
+    #
+    # Sets a content of a given frame.
+    #
+    # @param [String] html
+    #
+    # @example
+    #   browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+    #   frame = browser.frames[1]
+    #   frame.body # <html lang="en"><head><style>body {transition: opacity ease-in 0.2s; }...
+    #   frame.content = "<html><head></head><body><p>lol</p></body></html>"
+    #   frame.body # => <html><head></head><body><p>lol</p></body></html>
+    #
     def content=(html)
       evaluate_async(%(
         document.open();
@@ -49,16 +113,40 @@ module Ferrum
         document.close();
         arguments[1](true);
       ), @page.timeout, html)
+      @page.document_node_id
     end
     alias set_content content=
-    def execution_id
+    #
+    # Execution context id which is used by JS, each frame has it's own
+    # context in which JS evaluates. Locks for a page timeout and raises
+    # an error if an execution id hasn't been set yet, if id is set
+    # returns immediately.
+    #
+    # @return [Integer]
+    #
+    # @raise [NoExecutionContextError]
+    #
+    def execution_id!
       value = @execution_id.borrow(@page.timeout, &:itself)
       raise NoExecutionContextError if value.instance_of?(Object)
       value
     end
+    #
+    # Execution context id which is used by JS, each frame has it's own
+    # context in which JS evaluates.
+    #
+    # @return [Integer, nil]
+    #
+    def execution_id
+      value = @execution_id.value
+      return if value.instance_of?(Object)
+      value
+    end
     def execution_id=(value)
       if value.nil?
         @execution_id.try_take!

data/lib/ferrum/headers.rb CHANGED Viewed

@@ -7,20 +7,48 @@ module Ferrum
       @headers = {}
     end
+    #
+    # Get all headers.
+    #
+    # @return [Hash{String => String}]
+    #
     def get
       @headers
     end
+    #
+    # Set given headers. Eventually clear all headers and set given ones.
+    #
+    # @param [Hash{String => String}] headers
+    #   key-value pairs for example `"User-Agent" => "Browser"`.
+    #
+    # @return [true]
+    #
     def set(headers)
       clear
       add(headers)
     end
+    #
+    # Clear all headers.
+    #
+    # @return [true]
+    #
     def clear
       @headers = {}
       true
     end
+    #
+    # Adds given headers to already set ones.
+    #
+    # @param [Hash{String => String}] headers
+    #   key-value pairs for example `"Referer" => "http://example.com"`.
+    #
+    # @param [Boolean] permanent
+    #
+    # @return [true]
+    #
     def add(headers, permanent: true)
       if headers["Referer"]
         @page.referrer = headers["Referer"]

data/lib/ferrum/keyboard.rb CHANGED Viewed

@@ -30,19 +30,44 @@ module Ferrum
       @page = page
     end
+    #
+    # Dispatches a `keydown` event.
+    #
+    # @param [String, Symbol] key
+    #   Name of the key, such as `"a"`, `:enter`, or `:backspace`.
+    #
+    # @return [self]
+    #
     def down(key)
-      key = normalize_keys(Array(key))
+      key = normalize_keys(Array(key)).first
       type = key[:text] ? "keyDown" : "rawKeyDown"
       @page.command("Input.dispatchKeyEvent", slowmoable: true, type: type, **key)
       self
     end
+    #
+    # Dispatches a `keyup` event.
+    #
+    # @param [String, Symbol] key
+    #   Name of the key, such as `"a"`, `:enter`, or `:backspace`.
+    #
+    # @return [self]
+    #
     def up(key)
-      key = normalize_keys(Array(key))
+      key = normalize_keys(Array(key)).first
       @page.command("Input.dispatchKeyEvent", slowmoable: true, type: "keyUp", **key)
       self
     end
+    #
+    # Sends a keydown, keypress/input, and keyup event for each character in
+    # the text.
+    #
+    # @param [Array<String, Symbol, (Symbol, String)>] keys
+    #   The text to type into a focused element, `[:Shift, "s"], "tring"`.
+    #
+    # @return [self]
+    #
     def type(*keys)
       keys = normalize_keys(Array(keys))
@@ -55,15 +80,27 @@ module Ferrum
       self
     end
+    #
+    # Returns bitfield for a given keys.
+    #
+    # @param [Array<:alt, :ctrl, :command, :shift>] keys
+    #
+    # @return [Integer]
+    #
     def modifiers(keys)
       keys.map { |k| MODIFIERS[k.to_s] }.compact.reduce(0, :|)
     end
     private
+    # TODO: Refactor it, and try to simplify complexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/CyclomaticComplexity
     def normalize_keys(keys, pressed_keys = [], memo = [])
       case keys
       when Array
+        raise ArgumentError, "empty keys passed" if keys.empty?
         pressed_keys.push([])
         memo += combine_strings(keys).map do |key|
           normalize_keys(key, pressed_keys, memo)
@@ -82,6 +119,8 @@ module Ferrum
           to_options(key)
         end
       when String
+        raise ArgumentError, "empty keys passed" if keys.empty?
         pressed = pressed_keys.flatten
         keys.each_char.map do |char|
           key = KEYS[char] || {}
@@ -102,8 +141,12 @@ module Ferrum
             modifiers + [to_options(key)]
           end.flatten
         end
+      else
+        raise ArgumentError, "unexpected argument"
       end
     end
+    # rubocop:enable Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/CyclomaticComplexity
     def combine_strings(keys)
       keys

data/lib/ferrum/mouse.rb CHANGED Viewed

@@ -10,10 +10,50 @@ module Ferrum
       @x = @y = 0
     end
+    #
+    # Scroll page to a given x, y coordinates.
+    #
+    # @param [Integer] top
+    #  The pixel along the horizontal axis of the document that you want
+    #  displayed in the upper left.
+    #
+    # @param [Integer] left
+    #   The pixel along the vertical axis of the document that you want
+    #   displayed in the upper left.
+    #
+    # @example
+    #   browser.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
+    #   browser.mouse.scroll_to(0, 400)
+    #
     def scroll_to(top, left)
       tap { @page.execute("window.scrollTo(#{top}, #{left})") }
     end
+    #
+    # Click given coordinates, fires mouse move, down and up events.
+    #
+    # @param [Integer] x
+    #
+    # @param [Integer] y
+    #
+    # @param [Float] delay
+    #   Delay between mouse down and mouse up events.
+    #
+    # @param [Float] wait
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [:left, :right] :button (:left)
+    #   The mouse button to click.
+    #
+    # @option options [Integer] :count (1)
+    #
+    # @option options [Integer] :modifiers
+    #   Bitfield for key modifiers. See`keyboard.modifiers`.
+    #
+    # @return [self]
+    #
     def click(x:, y:, delay: 0, wait: CLICK_WAIT, **options)
       move(x: x, y: y)
       down(**options)
@@ -24,14 +64,58 @@ module Ferrum
       self
     end
+    #
+    # Mouse down for given coordinates.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [:left, :right] :button (:left)
+    #   The mouse button to click.
+    #
+    # @option options [Integer] :count (1)
+    #
+    # @option options [Integer] :modifiers
+    #   Bitfield for key modifiers. See`keyboard.modifiers`.
+    #
+    # @return [self]
+    #
     def down(**options)
       tap { mouse_event(type: "mousePressed", **options) }
     end
+    #
+    # Mouse up for given coordinates.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [:left, :right] :button (:left)
+    #   The mouse button to click.
+    #
+    # @option options [Integer] :count (1)
+    #
+    # @option options [Integer] :modifiers
+    #   Bitfield for key modifiers. See`keyboard.modifiers`.
+    #
+    # @return [self]
+    #
     def up(**options)
       tap { mouse_event(type: "mouseReleased", **options) }
     end
+    #
+    # Mouse move to given x and y.
+    #
+    # @param [Integer] x
+    #
+    # @param [Integer] y
+    #
+    # @param [Integer] steps
+    #   Sends intermediate mousemove events.
+    #
+    # @return [self]
+    #
     def move(x:, y:, steps: 1)
       from_x = @x
       from_y = @y

data/lib/ferrum/network/exchange.rb CHANGED Viewed

@@ -3,9 +3,38 @@
 module Ferrum
   class Network
     class Exchange
+      # ID of the request.
+      #
+      # @return String
       attr_reader :id
-      attr_accessor :intercepted_request, :request, :response, :error
+      # The intercepted request.
+      #
+      # @return [InterceptedRequest, nil]
+      attr_accessor :intercepted_request
+      # The request object.
+      #
+      # @return [Request, nil]
+      attr_accessor :request
+      # The response object.
+      #
+      # @return [Response, nil]
+      attr_accessor :response
+      # The error object.
+      #
+      # @return [Error, nil]
+      attr_accessor :error
+      #
+      # Initializes the network exchange.
+      #
+      # @param [Page] page
+      #
+      # @param [String] id
+      #
       def initialize(page, id)
         @id = id
         @page = page
@@ -13,35 +42,105 @@ module Ferrum
         @request = @response = @error = nil
       end
+      #
+      # Determines if the network exchange was caused by a page navigation
+      # event.
+      #
+      # @param [String] frame_id
+      #
+      # @return [Boolean]
+      #
       def navigation_request?(frame_id)
-        request.type?(:document) &&
-          request.frame_id == frame_id
+        request&.type?(:document) && request&.frame_id == frame_id
       end
+      #
+      # Determines if the network exchange has a request.
+      #
+      # @return [Boolean]
+      #
       def blank?
         !request
       end
+      #
+      # Determines if the request was intercepted and blocked.
+      #
+      # @return [Boolean]
+      #
       def blocked?
         intercepted? && intercepted_request.status?(:aborted)
       end
+      #
+      # Determines if the request was blocked, a response was returned, or if an
+      # error occurred.
+      #
+      # @return [Boolean]
+      #
       def finished?
-        blocked? || response || error
+        blocked? || response&.loaded? || !error.nil?
       end
+      #
+      # Determines if the network exchange is still not finished.
+      #
+      # @return [Boolean]
+      #
       def pending?
         !finished?
       end
+      #
+      # Determines if the exchange's request was intercepted.
+      #
+      # @return [Boolean]
+      #
       def intercepted?
-        intercepted_request
+        !intercepted_request.nil?
+      end
+      #
+      # Determines if the exchange is XHR.
+      #
+      # @return [Boolean]
+      #
+      def xhr?
+        !!request&.xhr?
+      end
+      #
+      # Determines if the exchange is a redirect.
+      #
+      # @return [Boolean]
+      #
+      def redirect?
+        response&.redirect?
+      end
+      #
+      # Returns request's URL.
+      #
+      # @return [String, nil]
+      #
+      def url
+        request&.url
       end
+      #
+      # Converts the network exchange into a request, response, and error tuple.
+      #
+      # @return [Array]
+      #
       def to_a
         [request, response, error]
       end
+      #
+      # Inspects the network exchange.
+      #
+      # @return [String]
+      #
       def inspect
         "#<#{self.class} " \
           "@id=#{@id.inspect} " \

data/lib/ferrum/network/intercepted_request.rb CHANGED Viewed

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
+require "ferrum/network/request_params"
 require "base64"
 module Ferrum
   class Network
     class InterceptedRequest
+      include RequestParams
       attr_accessor :request_id, :frame_id, :resource_type, :network_id, :status
       def initialize(page, params)
@@ -54,18 +57,6 @@ module Ferrum
         @page.command("Fetch.failRequest", requestId: request_id, errorReason: "BlockedByClient")
       end
-      def url
-        @request["url"]
-      end
-      def method
-        @request["method"]
-      end
-      def headers
-        @request["headers"]
-      end
       def initial_priority
         @request["initialPriority"]
       end

data/lib/ferrum/network/request.rb CHANGED Viewed

@@ -1,55 +1,94 @@
 # frozen_string_literal: true
+require "ferrum/network/request_params"
 require "time"
 module Ferrum
   class Network
+    #
+    # Represents a [Network.Request](https://chromedevtools.github.io/devtools-protocol/1-3/Network/#type-Request)
+    # object.
+    #
     class Request
+      include RequestParams
+      #
+      # Initializes the request object.
+      #
+      # @param [Hash{String => Object}] params
+      #   The parsed JSON attributes.
+      #
       def initialize(params)
         @params = params
         @request = @params["request"]
       end
+      #
+      # The request ID.
+      #
+      # @return [String]
+      #
       def id
         @params["requestId"]
       end
+      #
+      # The request resouce type.
+      #
+      # @return [String]
+      #
       def type
         @params["type"]
       end
+      #
+      # Determines if the request is of the given type.
+      #
+      # @param [String, Symbol] value
+      #   The type value to compare against.
+      #
+      # @return [Boolean]
+      #
       def type?(value)
         type.downcase == value.to_s.downcase
       end
-      def frame_id
-        @params["frameId"]
-      end
-      def url
-        @request["url"]
+      #
+      # Determines if the request is XHR.
+      #
+      # @return [Boolean]
+      #
+      def xhr?
+        type?("xhr")
       end
-      def url_fragment
-        @request["urlFragment"]
-      end
-      def method
-        @request["method"]
-      end
-      def headers
-        @request["headers"]
+      #
+      # The frame ID of the request.
+      #
+      # @return [String]
+      #
+      def frame_id
+        @params["frameId"]
       end
+      #
+      # The request timestamp.
+      #
+      # @return [Time]
+      #
       def time
         @time ||= Time.strptime(@params["wallTime"].to_s, "%s")
       end
-      def post_data
-        @request["postData"]
+      #
+      # Converts the request to a Hash.
+      #
+      # @return [Hash{String => Object}]
+      #   The params of the request.
+      #
+      def to_h
+        @params
       end
-      alias body post_data
     end
   end
 end