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

ferrum 0.11 → 0.13

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