ferrum 0.11 → 0.13

data/lib/ferrum/dialog.rb

@@ -10,6 +10,22 @@ module Ferrum
       @default_prompt = params["defaultPrompt"]
     end
 
+    #
+    # Accept dialog with given text or default prompt if applicable
+    #
+    # @param [String, nil] prompt_text
+    #
+    # @example
+    #   browser = Ferrum::Browser.new
+    #   browser.on(:dialog) do |dialog|
+    #     if dialog.match?(/bla-bla/)
+    #       dialog.accept
+    #     else
+    #       dialog.dismiss
+    #     end
+    #   end
+    #   browser.go_to("https://google.com")
+    #
     def accept(prompt_text = nil)
       options = { accept: true }
       response = prompt_text || default_prompt
@@ -17,6 +33,20 @@ module Ferrum
       @page.command("Page.handleJavaScriptDialog", slowmoable: true, **options)
     end
 
+    #
+    # Dismiss dialog.
+    #
+    # @example
+    #   browser = Ferrum::Browser.new
+    #   browser.on(:dialog) do |dialog|
+    #     if dialog.match?(/bla-bla/)
+    #       dialog.accept
+    #     else
+    #       dialog.dismiss
+    #     end
+    #   end
+    #   browser.go_to("https://google.com")
+    #
     def dismiss
       @page.command("Page.handleJavaScriptDialog", slowmoable: true, accept: false)
     end

data/lib/ferrum/errors.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Ferrum
+  class Error               < StandardError; end
+  class NoSuchPageError     < Error; end
+  class NoSuchTargetError   < Error; end
+  class NotImplementedError < Error; end
+  class BinaryNotFoundError < Error; end
+  class EmptyPathError < Error; end
+
+  class StatusError < Error
+    def initialize(url, message = nil)
+      super(message || "Request to #{url} failed to reach server, check DNS and server status")
+    end
+  end
+
+  class PendingConnectionsError < StatusError
+    attr_reader :pendings
+
+    def initialize(url, pendings = [])
+      @pendings = pendings
+
+      message = "Request to #{url} reached server, but there are still pending connections: #{pendings.join(', ')}"
+
+      super(url, message)
+    end
+  end
+
+  class TimeoutError < Error
+    def message
+      "Timed out waiting for response. It's possible that this happened " \
+        "because something took a very long time (for example a page load " \
+        "was slow). If so, setting the :timeout option to a higher value might " \
+        "help."
+    end
+  end
+
+  class ScriptTimeoutError < Error
+    def message
+      "Timed out waiting for evaluated script to return a value"
+    end
+  end
+
+  class ProcessTimeoutError < Error
+    attr_reader :output
+
+    def initialize(timeout, output)
+      @output = output
+      super("Browser did not produce websocket url within #{timeout} seconds, try to increase `:process_timeout`. See https://github.com/rubycdp/ferrum#customization")
+    end
+  end
+
+  class DeadBrowserError < Error
+    def initialize(message = "Browser is dead or given window is closed")
+      super
+    end
+  end
+
+  class NodeMovingError < Error
+    def initialize(node, prev, current)
+      @node = node
+      @prev = prev
+      @current = current
+      super(message)
+    end
+
+    def message
+      "#{@node.inspect} that you're trying to click is moving, hence " \
+        "we cannot. Previously it was at #{@prev.inspect} but now at " \
+        "#{@current.inspect}."
+    end
+  end
+
+  class CoordinatesNotFoundError < Error
+    def initialize(message = "Could not compute content quads")
+      super
+    end
+  end
+
+  class BrowserError < Error
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super(response["message"])
+    end
+
+    def code
+      response["code"]
+    end
+
+    def data
+      response["data"]
+    end
+  end
+
+  class NodeNotFoundError < BrowserError; end
+
+  class NoExecutionContextError < BrowserError
+    def initialize(response = nil)
+      response ||= { "message" => "There's no context available" }
+      super(response)
+    end
+  end
+
+  class JavaScriptError < BrowserError
+    attr_reader :class_name, :message, :stack_trace
+
+    def initialize(response, stack_trace = nil)
+      @class_name, @message = response.values_at("className", "description")
+      @stack_trace = stack_trace
+      super(response.merge("message" => @message))
+    end
+  end
+end

data/lib/ferrum/frame/dom.rb

@@ -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

@@ -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 = "function() { return %s }" % expression
+        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() {
@@ -66,12 +64,24 @@ module Ferrum
           }
         JS
 
-        expression = template % [wait * 1000, expression]
+        expression = format(template, wait * 1000, expression)
         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 = "function() { %s }" % expression
+        expression = format("function() { %s }", expression)
         call(expression: expression, arguments: args, handle: false, returnByValue: true)
         true
       end
@@ -82,46 +92,17 @@ module Ferrum
 
       def evaluate_on(node:, expression:, by_value: true, wait: 0)
         options = { handle: true }
-        expression = "function() { return %s }" % expression
+        expression = format("function() { return %s }", expression)
         options = { handle: false, returnByValue: true } if by_value
         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]
-        attempts, sleep = INTERMITTENT_ATTEMPTS, INTERMITTENT_SLEEP
 
-        Ferrum.with_attempts(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
@@ -131,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",
@@ -141,7 +122,7 @@ module Ferrum
           handle_error(response)
           response = response["result"]
 
-          handle ? handle_response(response) : response.dig("value")
+          handle ? handle_response(response) : response["value"]
         end
       end
 
@@ -154,7 +135,7 @@ module Ferrum
         when /\AError: timed out promise/
           raise ScriptTimeoutError
         else
-          raise JavaScriptError.new(result)
+          raise JavaScriptError.new(result, response.dig("exceptionDetails", "stackTrace"))
         end
       end
 
@@ -171,16 +152,17 @@ module Ferrum
 
           case response["subtype"]
           when "node"
-              # We cannot store object_id in the node because page can be reloaded
-              # and node destroyed so we need to retrieve it each time for given id.
-              # Though we can try to subscribe to `DOM.childNodeRemoved` and
-              # `DOM.childNodeInserted` in the future.
-              node_id = @page.command("DOM.requestNode", objectId: object_id)["nodeId"]
-              description = @page.command("DOM.describeNode", nodeId: node_id)["node"]
-              Node.new(self, @page.target_id, node_id, description)
+            # We cannot store object_id in the node because page can be reloaded
+            # and node destroyed so we need to retrieve it each time for given id.
+            # Though we can try to subscribe to `DOM.childNodeRemoved` and
+            # `DOM.childNodeInserted` in the future.
+            node_id = @page.command("DOM.requestNode", objectId: object_id)["nodeId"]
+            description = @page.command("DOM.describeNode", nodeId: node_id)["node"]
+            Node.new(self, @page.target_id, node_id, description)
           when "array"
             reduce_props(object_id, []) do |memo, key, value|
-              next(memo) unless (Integer(key) rescue nil)
+              next(memo) unless Integer(key, exception: false)
+
               value = value["objectId"] ? handle_response(value) : value["value"]
               memo.insert(key.to_i, value)
             end.compact
@@ -212,11 +194,12 @@ module Ferrum
 
       def reduce_props(object_id, to)
         if cyclic?(object_id).dig("result", "value")
-          return to.is_a?(Array) ? [cyclic_object] : cyclic_object
+          to.is_a?(Array) ? [cyclic_object] : cyclic_object
         else
           props = @page.command("Runtime.getProperties", ownProperties: true, objectId: object_id)
           props["result"].reduce(to) do |memo, prop|
             next(memo) unless prop["enumerable"]
+
             yield(memo, prop["name"], prop["value"])
           end
         end