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

ferrum 0.12 → 0.13

Files changed (36) hide show

checksums.yaml +4 -4
data/README.md +15 -20
data/lib/ferrum/browser/client.rb +4 -4
data/lib/ferrum/browser/command.rb +5 -6
data/lib/ferrum/browser/options/base.rb +1 -4
data/lib/ferrum/browser/options/chrome.rb +14 -9
data/lib/ferrum/browser/options/firefox.rb +3 -6
data/lib/ferrum/browser/options.rb +84 -0
data/lib/ferrum/browser/process.rb +5 -6
data/lib/ferrum/browser/version_info.rb +71 -0
data/lib/ferrum/browser/xvfb.rb +1 -1
data/lib/ferrum/browser.rb +176 -62
data/lib/ferrum/context.rb +3 -2
data/lib/ferrum/contexts.rb +2 -2
data/lib/ferrum/cookies/cookie.rb +126 -0
data/lib/ferrum/cookies.rb +86 -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 +90 -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 +86 -5
data/lib/ferrum/network/request.rb +64 -0
data/lib/ferrum/network/response.rb +83 -1
data/lib/ferrum/network.rb +160 -0
data/lib/ferrum/page/animation.rb +16 -0
data/lib/ferrum/page/frames.rb +66 -11
data/lib/ferrum/page/screenshot.rb +91 -0
data/lib/ferrum/page/tracing.rb +26 -0
data/lib/ferrum/page.rb +151 -32
data/lib/ferrum/proxy.rb +91 -2
data/lib/ferrum/target.rb +6 -4
data/lib/ferrum/version.rb +1 -1
metadata +5 -2

data/lib/ferrum/frame/dom.rb CHANGED Viewed

@@ -20,10 +20,59 @@
 module Ferrum
   class Frame
     module DOM
+      SCRIPT_SRC_TAG = <<~JS
+        const script = document.createElement("script");
+        script.src = arguments[0];
+        script.type = arguments[1];
+        script.onload = arguments[2];
+        document.head.appendChild(script);
+      JS
+      SCRIPT_TEXT_TAG = <<~JS
+        const script = document.createElement("script");
+        script.text = arguments[0];
+        script.type = arguments[1];
+        document.head.appendChild(script);
+        arguments[2]();
+      JS
+      STYLE_TAG = <<~JS
+        const style = document.createElement("style");
+        style.type = "text/css";
+        style.appendChild(document.createTextNode(arguments[0]));
+        document.head.appendChild(style);
+        arguments[1]();
+      JS
+      LINK_TAG = <<~JS
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = arguments[0];
+        link.onload = arguments[1];
+        document.head.appendChild(link);
+      JS
+      #
+      # Returns current top window `location href`.
+      #
+      # @return [String]
+      #   The window's current URL.
+      #
+      # @example
+      #   browser.go_to("https://google.com/")
+      #   browser.current_url # => "https://www.google.com/"
+      #
       def current_url
         evaluate("window.top.location.href")
       end
+      #
+      # Returns current top window title.
+      #
+      # @return [String]
+      #   The window's current title.
+      #
+      # @example
+      #   browser.go_to("https://google.com/")
+      #   browser.current_title # => "Google"
+      #
       def current_title
         evaluate("window.top.document.title")
       end
@@ -32,10 +81,36 @@ module Ferrum
         evaluate("document.doctype && new XMLSerializer().serializeToString(document.doctype)")
       end
+      #
+      # Returns current page's html.
+      #
+      # @return [String]
+      #   The HTML source of the current page.
+      #
+      # @example
+      #   browser.go_to("https://google.com/")
+      #   browser.body # => '<html itemscope="" itemtype="http://schema.org/WebPage" lang="ru"><head>...
+      #
       def body
         evaluate("document.documentElement.outerHTML")
       end
+      #
+      # Finds nodes by using a XPath selector.
+      #
+      # @param [String] selector
+      #   The XPath selector.
+      #
+      # @param [Node, nil] within
+      #   The parent node to search within.
+      #
+      # @return [Array<Node>]
+      #   The matching nodes.
+      #
+      # @example
+      #   browser.go_to("https://github.com/")
+      #   browser.xpath("//a[@aria-label='Issues you created']") # => [Node]
+      #
       def xpath(selector, within: nil)
         expr = <<~JS
           function(selector, within) {
@@ -54,6 +129,22 @@ module Ferrum
         evaluate_func(expr, selector, within)
       end
+      #
+      # Finds a node by using a XPath selector.
+      #
+      # @param [String] selector
+      #   The XPath selector.
+      #
+      # @param [Node, nil] within
+      #   The parent node to search within.
+      #
+      # @return [Node, nil]
+      #   The matching node.
+      #
+      # @example
+      #   browser.go_to("https://github.com/")
+      #   browser.at_xpath("//a[@aria-label='Issues you created']") # => Node
+      #
       def at_xpath(selector, within: nil)
         expr = <<~JS
           function(selector, within) {
@@ -65,6 +156,22 @@ module Ferrum
         evaluate_func(expr, selector, within)
       end
+      #
+      # Finds nodes by using a CSS path selector.
+      #
+      # @param [String] selector
+      #   The CSS path selector.
+      #
+      # @param [Node, nil] within
+      #   The parent node to search within.
+      #
+      # @return [Array<Node>]
+      #   The matching nodes.
+      #
+      # @example
+      #   browser.go_to("https://github.com/")
+      #   browser.css("a[aria-label='Issues you created']") # => [Node]
+      #
       def css(selector, within: nil)
         expr = <<~JS
           function(selector, within) {
@@ -76,6 +183,22 @@ module Ferrum
         evaluate_func(expr, selector, within)
       end
+      #
+      # Finds a node by using a CSS path selector.
+      #
+      # @param [String] selector
+      #   The CSS path selector.
+      #
+      # @param [Node, nil] within
+      #   The parent node to search within.
+      #
+      # @return [Node, nil]
+      #   The matching node.
+      #
+      # @example
+      #   browser.go_to("https://github.com/")
+      #   browser.at_css("a[aria-label='Issues you created']") # => Node
+      #
       def at_css(selector, within: nil)
         expr = <<~JS
           function(selector, within) {
@@ -86,6 +209,60 @@ module Ferrum
         evaluate_func(expr, selector, within)
       end
+      #
+      # Adds a `<script>` tag to the document.
+      #
+      # @param [String, nil] url
+      #
+      # @param [String, nil] path
+      #
+      # @param [String, nil] content
+      #
+      # @param [String] type
+      #
+      # @example
+      #   browser.add_script_tag(url: "http://example.com/stylesheet.css") # => true
+      #
+      def add_script_tag(url: nil, path: nil, content: nil, type: "text/javascript")
+        expr, *args = if url
+                        [SCRIPT_SRC_TAG, url, type]
+                      elsif path || content
+                        if path
+                          content = File.read(path)
+                          content += "\n//# sourceURL=#{path}"
+                        end
+                        [SCRIPT_TEXT_TAG, content, type]
+                      end
+        evaluate_async(expr, @page.timeout, *args)
+      end
+      #
+      # Adds a `<style>` tag to the document.
+      #
+      # @param [String, nil] url
+      #
+      # @param [String, nil] path
+      #
+      # @param [String, nil] content
+      #
+      # @example
+      #   browser.add_style_tag(content: "h1 { font-size: 40px; }") # => true
+      #
+      def add_style_tag(url: nil, path: nil, content: nil)
+        expr, *args = if url
+                        [LINK_TAG, url]
+                      elsif path || content
+                        if path
+                          content = File.read(path)
+                          content += "\n//# sourceURL=#{path}"
+                        end
+                        [STYLE_TAG, content]
+                      end
+        evaluate_async(expr, @page.timeout, *args)
+      end
     end
   end
 end

data/lib/ferrum/frame/runtime.rb CHANGED Viewed

@@ -16,40 +16,38 @@ module Ferrum
       INTERMITTENT_ATTEMPTS = ENV.fetch("FERRUM_INTERMITTENT_ATTEMPTS", 6).to_i
       INTERMITTENT_SLEEP = ENV.fetch("FERRUM_INTERMITTENT_SLEEP", 0.1).to_f
-      SCRIPT_SRC_TAG = <<~JS
-        const script = document.createElement("script");
-        script.src = arguments[0];
-        script.type = arguments[1];
-        script.onload = arguments[2];
-        document.head.appendChild(script);
-      JS
-      SCRIPT_TEXT_TAG = <<~JS
-        const script = document.createElement("script");
-        script.text = arguments[0];
-        script.type = arguments[1];
-        document.head.appendChild(script);
-        arguments[2]();
-      JS
-      STYLE_TAG = <<~JS
-        const style = document.createElement("style");
-        style.type = "text/css";
-        style.appendChild(document.createTextNode(arguments[0]));
-        document.head.appendChild(style);
-        arguments[1]();
-      JS
-      LINK_TAG = <<~JS
-        const link = document.createElement("link");
-        link.rel = "stylesheet";
-        link.href = arguments[0];
-        link.onload = arguments[1];
-        document.head.appendChild(link);
-      JS
+      #
+      # Evaluate and return result for given JS expression.
+      #
+      # @param [String] expression
+      #   The JavaScript to evaluate.
+      #
+      # @param [Array] args
+      #   Additional arguments to pass to the JavaScript code.
+      #
+      # @example
+      #   browser.evaluate("[window.scrollX, window.scrollY]")
+      #
       def evaluate(expression, *args)
         expression = format("function() { return %s }", expression)
         call(expression: expression, arguments: args)
       end
+      #
+      # Evaluate asynchronous expression and return result.
+      #
+      # @param [String] expression
+      #   The JavaScript to evaluate.
+      #
+      # @param [Integer] wait
+      #   How long we should wait for Promise to resolve or reject.
+      #
+      # @param [Array] args
+      #   Additional arguments to pass to the JavaScript code.
+      #
+      # @example
+      #   browser.evaluate_async(%(arguments[0]({foo: "bar"})), 5) # => { "foo" => "bar" }
+      #
       def evaluate_async(expression, wait, *args)
         template = <<~JS
           function() {
@@ -70,6 +68,18 @@ module Ferrum
         call(expression: expression, arguments: args, awaitPromise: true)
       end
+      #
+      # Execute expression. Doesn't return the result.
+      #
+      # @param [String] expression
+      #   The JavaScript to evaluate.
+      #
+      # @param [Array] args
+      #   Additional arguments to pass to the JavaScript code.
+      #
+      # @example
+      #   browser.execute(%(1 + 1)) # => true
+      #
       def execute(expression, *args)
         expression = format("function() { %s }", expression)
         call(expression: expression, arguments: args, handle: false, returnByValue: true)
@@ -87,42 +97,12 @@ module Ferrum
         call(expression: expression, on: node, wait: wait, **options)
       end
-      def add_script_tag(url: nil, path: nil, content: nil, type: "text/javascript")
-        expr, *args = if url
-                        [SCRIPT_SRC_TAG, url, type]
-                      elsif path || content
-                        if path
-                          content = File.read(path)
-                          content += "\n//# sourceURL=#{path}"
-                        end
-                        [SCRIPT_TEXT_TAG, content, type]
-                      end
-        evaluate_async(expr, @page.timeout, *args)
-      end
-      def add_style_tag(url: nil, path: nil, content: nil)
-        expr, *args = if url
-                        [LINK_TAG, url]
-                      elsif path || content
-                        if path
-                          content = File.read(path)
-                          content += "\n//# sourceURL=#{path}"
-                        end
-                        [STYLE_TAG, content]
-                      end
-        evaluate_async(expr, @page.timeout, *args)
-      end
       private
       def call(expression:, arguments: [], on: nil, wait: 0, handle: true, **options)
         errors = [NodeNotFoundError, NoExecutionContextError]
-        sleep = INTERMITTENT_SLEEP
-        attempts = INTERMITTENT_ATTEMPTS
-        Utils::Attempt.with_retry(errors: errors, max: attempts, wait: sleep) do
+        Utils::Attempt.with_retry(errors: errors, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP) do
           params = options.dup
           if on
@@ -132,7 +112,7 @@ module Ferrum
           end
           if params[:executionContextId].nil? && params[:objectId].nil?
-            params = params.merge(executionContextId: execution_id)
+            params = params.merge(executionContextId: execution_id!)
           end
           response = @page.command("Runtime.callFunctionOn",

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();
@@ -52,13 +116,36 @@ module Ferrum
     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