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

ferrum 0.12 → 0.14

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