RubyGems - ferrum - Versions diffs - 0.11 → 0.13 - Mend

ferrum 0.11 → 0.13

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 (50) hide show

checksums.yaml +4 -4
data/LICENSE +1 -1
data/README.md +174 -30
data/lib/ferrum/browser/binary.rb +46 -0
data/lib/ferrum/browser/client.rb +17 -16
data/lib/ferrum/browser/command.rb +10 -12
data/lib/ferrum/browser/options/base.rb +2 -11
data/lib/ferrum/browser/options/chrome.rb +29 -18
data/lib/ferrum/browser/options/firefox.rb +13 -9
data/lib/ferrum/browser/options.rb +84 -0
data/lib/ferrum/browser/process.rb +45 -40
data/lib/ferrum/browser/subscriber.rb +1 -3
data/lib/ferrum/browser/version_info.rb +71 -0
data/lib/ferrum/browser/web_socket.rb +9 -12
data/lib/ferrum/browser/xvfb.rb +4 -8
data/lib/ferrum/browser.rb +193 -47
data/lib/ferrum/context.rb +9 -4
data/lib/ferrum/contexts.rb +12 -10
data/lib/ferrum/cookies/cookie.rb +126 -0
data/lib/ferrum/cookies.rb +93 -55
data/lib/ferrum/dialog.rb +30 -0
data/lib/ferrum/errors.rb +115 -0
data/lib/ferrum/frame/dom.rb +177 -0
data/lib/ferrum/frame/runtime.rb +58 -75
data/lib/ferrum/frame.rb +118 -23
data/lib/ferrum/headers.rb +30 -2
data/lib/ferrum/keyboard.rb +56 -13
data/lib/ferrum/mouse.rb +92 -7
data/lib/ferrum/network/auth_request.rb +7 -2
data/lib/ferrum/network/exchange.rb +97 -12
data/lib/ferrum/network/intercepted_request.rb +10 -8
data/lib/ferrum/network/request.rb +69 -0
data/lib/ferrum/network/response.rb +85 -3
data/lib/ferrum/network.rb +285 -36
data/lib/ferrum/node.rb +69 -23
data/lib/ferrum/page/animation.rb +16 -1
data/lib/ferrum/page/frames.rb +111 -30
data/lib/ferrum/page/screenshot.rb +142 -65
data/lib/ferrum/page/stream.rb +38 -0
data/lib/ferrum/page/tracing.rb +97 -0
data/lib/ferrum/page.rb +224 -60
data/lib/ferrum/proxy.rb +147 -0
data/lib/ferrum/{rbga.rb → rgba.rb} +4 -2
data/lib/ferrum/target.rb +7 -4
data/lib/ferrum/utils/attempt.rb +20 -0
data/lib/ferrum/utils/elapsed_time.rb +27 -0
data/lib/ferrum/utils/platform.rb +28 -0
data/lib/ferrum/version.rb +1 -1
data/lib/ferrum.rb +4 -146
metadata +63 -51

data/lib/ferrum/frame.rb CHANGED Viewed

@@ -5,37 +5,108 @@ require "ferrum/frame/runtime"
 module Ferrum
   class Frame
-    include DOM, Runtime
+    include DOM
+    include Runtime
-    attr_reader :page, :parent_id, :state
-    attr_accessor :id, :name
+    STATE_VALUES = %i[
+      started_loading
+      navigated
+      stopped_loading
+    ].freeze
+    # 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)
-      @execution_id = nil
-      @id, @page, @parent_id = id, page, parent_id
+      @id = id
+      @page = page
+      @parent_id = parent_id
+      @execution_id = Concurrent::MVar.new
     end
-    # Can be one of:
-    # * started_loading
-    # * navigated
-    # * stopped_loading
     def state=(value)
+      raise ArgumentError unless STATE_VALUES.include?(value)
       @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
-    def set_content(html)
+    #
+    # 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();
         document.write(arguments[0]);
@@ -43,29 +114,53 @@ module Ferrum
         arguments[1](true);
       ), @page.timeout, html)
     end
+    alias set_content content=
-    def execution_id?(execution_id)
-      @execution_id == 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
-      raise NoExecutionContextError unless @execution_id
-      @execution_id
-    rescue NoExecutionContextError
-      @page.event.reset
-      @page.event.wait(@page.timeout) ? retry : raise
-    end
+      value = @execution_id.value
+      return if value.instance_of?(Object)
-    def set_execution_id(value)
-      @execution_id ||= value
+      value
     end
-    def reset_execution_id
-      @execution_id = nil
+    def execution_id=(value)
+      if value.nil?
+        @execution_id.try_take!
+      else
+        @execution_id.try_put!(value)
+      end
     end
     def inspect
-      %(#<#{self.class} @id=#{@id.inspect} @parent_id=#{@parent_id.inspect} @name=#{@name.inspect} @state=#{@state.inspect} @execution_id=#{@execution_id.inspect}>)
+      "#<#{self.class} " \
+        "@id=#{@id.inspect} " \
+        "@parent_id=#{@parent_id.inspect} " \
+        "@name=#{@name.inspect} " \
+        "@state=#{@state.inspect} " \
+        "@execution_id=#{@execution_id.inspect}>"
     end
   end
 end

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"]
@@ -39,12 +67,12 @@ module Ferrum
     private
     def set_overrides(user_agent: nil, accept_language: nil, platform: nil)
-      options = Hash.new
+      options = {}
       options[:userAgent] = user_agent || @page.browser.default_user_agent
       options[:acceptLanguage] = accept_language if accept_language
       options[:platform] if platform
-      @page.command("Network.setUserAgentOverride", **options) if !options.empty?
+      @page.command("Network.setUserAgentOverride", **options) unless options.empty?
     end
   end
 end

data/lib/ferrum/keyboard.rb CHANGED Viewed

@@ -4,14 +4,14 @@ require "json"
 module Ferrum
   class Keyboard
-    KEYS = JSON.parse(File.read(File.expand_path("../keyboard.json", __FILE__)))
+    KEYS = JSON.parse(File.read(File.expand_path("keyboard.json", __dir__)))
     MODIFIERS = { "alt" => 1, "ctrl" => 2, "control" => 2,
-                  "meta" => 4, "command" => 4, "shift" => 8 }
+                  "meta" => 4, "command" => 4, "shift" => 8 }.freeze
     KEYS_MAPPING = {
       cancel: "Cancel", help: "Help", backspace: "Backspace", tab: "Tab",
       clear: "Clear", return: "Enter", enter: "Enter", shift: "Shift",
       ctrl: "Control", control: "Control", alt: "Alt", pause: "Pause",
-      escape: "Escape", space: "Space",  pageup: "PageUp", page_up: "PageUp",
+      escape: "Escape", space: "Space", pageup: "PageUp", page_up: "PageUp",
       pagedown: "PageDown", page_down: "PageDown", end: "End", home: "Home",
       left: "ArrowLeft", up: "ArrowUp", right: "ArrowRight",
       down: "ArrowDown", insert: "Insert", delete: "Delete",
@@ -23,26 +23,51 @@ module Ferrum
       separator: "NumpadDecimal", subtract: "NumpadSubtract",
       decimal: "NumpadDecimal", divide: "NumpadDivide", f1: "F1", f2: "F2",
       f3: "F3", f4: "F4", f5: "F5", f6: "F6", f7: "F7", f8: "F8", f9: "F9",
-      f10: "F10", f11: "F11", f12: "F12", meta: "Meta", command: "Meta",
-    }
+      f10: "F10", f11: "F11", f12: "F12", meta: "Meta", command: "Meta"
+    }.freeze
     def initialize(page)
       @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)
@@ -77,33 +114,39 @@ module Ferrum
           pressed_keys.last.push(key)
           nil
         else
-          _key = KEYS.fetch(KEYS_MAPPING[key.to_sym] || key.to_sym)
-          _key[:modifiers] = pressed_keys.flatten.map { |k| MODIFIERS[k] }.reduce(0, :|)
-          to_options(_key)
+          key = KEYS.fetch(KEYS_MAPPING[key.to_sym] || key.to_sym)
+          key[:modifiers] = pressed_keys.flatten.map { |k| MODIFIERS[k] }.reduce(0, :|)
+          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] || {}
           if pressed.empty?
-            key = KEYS[char] || {}
             key = key.merge(text: char, unmodifiedText: char)
             [to_options(key)]
           else
-            key = KEYS[char] || {}
             text = pressed == ["shift"] ? char.upcase : char
             key = key.merge(
               text: text,
               unmodifiedText: text,
               isKeypad: key["location"] == 3,
-              modifiers: pressed.map { |k| MODIFIERS[k] }.reduce(0, :|),
+              modifiers: pressed.map { |k| MODIFIERS[k] }.reduce(0, :|)
             )
             modifiers = pressed.map { |k| to_options(KEYS.fetch(KEYS_MAPPING[k.to_sym])) }
             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,21 +64,67 @@ 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, from_y = @x, @y
-      @x, @y = x, y
+      from_x = @x
+      from_y = @y
+      @x = x
+      @y = y
       steps.times do |i|
-        new_x = from_x + (@x - from_x) * ((i + 1) / steps.to_f)
-        new_y = from_y + (@y - from_y) * ((i + 1) / steps.to_f)
+        new_x = from_x + ((@x - from_x) * ((i + 1) / steps.to_f))
+        new_y = from_y + ((@y - from_y) * ((i + 1) / steps.to_f))
         @page.command("Input.dispatchMouseEvent",
                       slowmoable: true,
@@ -61,9 +147,8 @@ module Ferrum
     def validate_button(button)
       button = button.to_s
-      unless VALID_BUTTONS.include?(button)
-        raise "Invalid button: #{button}"
-      end
+      raise "Invalid button: #{button}" unless VALID_BUTTONS.include?(button)
       button
     end
   end

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

@@ -6,7 +6,8 @@ module Ferrum
       attr_accessor :request_id, :frame_id, :resource_type
       def initialize(page, params)
-        @page, @params = page, params
+        @page = page
+        @params = params
         @request_id = params["requestId"]
         @frame_id = params["frameId"]
         @resource_type = params["resourceType"]
@@ -55,7 +56,11 @@ module Ferrum
       end
       def inspect
-        %(#<#{self.class} @request_id=#{@request_id.inspect} @frame_id=#{@frame_id.inspect} @resource_type=#{@resource_type.inspect} @request=#{@request.inspect}>)
+        "#<#{self.class} " \
+          "@request_id=#{@request_id.inspect} " \
+          "@frame_id=#{@frame_id.inspect} " \
+          "@resource_type=#{@resource_type.inspect} " \
+          "@request=#{@request.inspect}>"
       end
     end
   end

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

@@ -3,48 +3,133 @@
 module Ferrum
   class Network
     class Exchange
+      # ID of the request.
+      #
+      # @return String
       attr_reader :id
+      # The intercepted request.
+      #
+      # @return [InterceptedRequest, nil]
       attr_accessor :intercepted_request
-      attr_accessor :request, :response, :error
+      # 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)
-        @page, @id = page, id
+        @id = id
+        @page = page
         @intercepted_request = nil
         @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_request && intercepted_request.status?(:aborted)
+        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.nil? || !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.nil?
+      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} "\
-        "@intercepted_request=#{@intercepted_request.inspect} "\
-        "@request=#{@request.inspect} "\
-        "@response=#{@response.inspect} "\
-        "@error=#{@error.inspect}>"
+        "#<#{self.class} " \
+          "@id=#{@id.inspect} " \
+          "@intercepted_request=#{@intercepted_request.inspect} " \
+          "@request=#{@request.inspect} " \
+          "@response=#{@response.inspect} " \
+          "@error=#{@error.inspect}>"
       end
     end
   end