ferrum 0.12 → 0.14

data/lib/ferrum/cookies.rb

@@ -1,68 +1,119 @@
 # frozen_string_literal: true
 
+require "ferrum/cookies/cookie"
+
 module Ferrum
   class Cookies
-    class Cookie
-      attr_reader :attributes
-
-      def initialize(attributes)
-        @attributes = attributes
-      end
-
-      def name
-        @attributes["name"]
-      end
-
-      def value
-        @attributes["value"]
-      end
-
-      def domain
-        @attributes["domain"]
-      end
-
-      def path
-        @attributes["path"]
-      end
-
-      def samesite
-        @attributes["sameSite"]
-      end
-
-      def size
-        @attributes["size"]
-      end
+    include Enumerable
 
-      def secure?
-        @attributes["secure"]
-      end
+    def initialize(page)
+      @page = page
+    end
 
-      def httponly?
-        @attributes["httpOnly"]
-      end
+    #
+    # Enumerates over all cookies.
+    #
+    # @yield [cookie]
+    #   The given block will be passed each cookie.
+    #
+    # @yieldparam [Cookie] cookie
+    #   A cookie in the browser.
+    #
+    # @return [Enumerator]
+    #   If no block is given, an Enumerator object will be returned.
+    #
+    def each
+      return enum_for(__method__) unless block_given?
 
-      def session?
-        @attributes["session"]
-      end
+      cookies = @page.command("Network.getAllCookies")["cookies"]
 
-      def expires
-        Time.at(@attributes["expires"]) if @attributes["expires"].positive?
+      cookies.each do |c|
+        yield Cookie.new(c)
       end
     end
 
-    def initialize(page)
-      @page = page
-    end
-
+    #
+    # Returns cookies hash.
+    #
+    # @return [Hash{String => Cookie}]
+    #
+    # @example
+    #   browser.cookies.all # => {
+    #   #  "NID" => #<Ferrum::Cookies::Cookie:0x0000558624b37a40 @attributes={
+    #   #     "name"=>"NID", "value"=>"...", "domain"=>".google.com", "path"=>"/",
+    #   #     "expires"=>1583211046.575681, "size"=>178, "httpOnly"=>true, "secure"=>false, "session"=>false
+    #   #  }>
+    #   # }
+    #
     def all
-      cookies = @page.command("Network.getAllCookies")["cookies"]
-      cookies.to_h { |c| [c["name"], Cookie.new(c)] }
+      each.to_h do |cookie|
+        [cookie.name, cookie]
+      end
     end
 
+    #
+    # Returns cookie.
+    #
+    # @param [String] name
+    #   The cookie name to fetch.
+    #
+    # @return [Cookie, nil]
+    #   The cookie with the matching name.
+    #
+    # @example
+    #   browser.cookies["NID"] # =>
+    #   # <Ferrum::Cookies::Cookie:0x0000558624b67a88 @attributes={
+    #   #  "name"=>"NID", "value"=>"...", "domain"=>".google.com",
+    #   #  "path"=>"/", "expires"=>1583211046.575681, "size"=>178,
+    #   #  "httpOnly"=>true, "secure"=>false, "session"=>false
+    #   # }>
+    #
     def [](name)
-      all[name]
+      find { |cookie| cookie.name == name }
     end
 
+    #
+    # Sets a cookie.
+    #
+    # @param [Hash{Symbol => Object}, Cookie] options
+    #
+    # @option options [String] :name
+    #   The cookie param name.
+    #
+    # @option options [String] :value
+    #   The cookie param value.
+    #
+    # @option options [String] :domain
+    #   The domain the cookie belongs to.
+    #
+    # @option options [String] :path
+    #   The path that the cookie is bound to.
+    #
+    # @option options [Integer] :expires
+    #   When the cookie will expire.
+    #
+    # @option options [Integer] :size
+    #   The size of the cookie.
+    #
+    # @option options [Boolean] :httponly
+    #   Specifies whether the cookie `HttpOnly`.
+    #
+    # @option options [Boolean] :secure
+    #   Specifies whether the cookie is marked as `Secure`.
+    #
+    # @option options [String] :samesite
+    #   Specifies whether the cookie is `SameSite`.
+    #
+    # @option options [Boolean] :session
+    #   Specifies whether the cookie is a session cookie.
+    #
+    # @example
+    #   browser.cookies.set(name: "stealth", value: "omg", domain: "google.com") # => true
+    #
+    # @example
+    #   nid_cookie = browser.cookies["NID"] # => <Ferrum::Cookies::Cookie:0x0000558624b67a88>
+    #   browser.cookies.set(nid_cookie) # => true
+    #
     def set(options)
       cookie = (
         options.is_a?(Cookie) ? options.attributes : options
@@ -79,7 +130,21 @@ module Ferrum
       @page.command("Network.setCookie", **cookie)["success"]
     end
 
-    # Supports :url, :domain and :path options
+    #
+    # Removes given cookie.
+    #
+    # @param [String] name
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [String] :domain
+    #
+    # @option options [String] :url
+    #
+    # @example
+    #   browser.cookies.remove(name: "stealth", domain: "google.com") # => true
+    #
     def remove(name:, **options)
       raise "Specify :domain or :url option" if !options[:domain] && !options[:url] && !default_domain
 
@@ -91,6 +156,14 @@ module Ferrum
       true
     end
 
+    #
+    # Removes all cookies for current page.
+    #
+    # @return [true]
+    #
+    # @example
+    #   browser.cookies.clear # => true
+    #
     def clear
       @page.command("Network.clearBrowserCookies")
       true

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/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 = 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",