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

ferrum 0.12 → 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 (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