ferrum 0.14 → 0.16

data/lib/ferrum/network.rb

@@ -41,7 +41,7 @@ module Ferrum
     end
 
     #
-    # Waits for network idle or raises {Ferrum::TimeoutError} error.
+    # Waits for network idle.
     #
     # @param [Integer] connections
     #   how many connections are allowed for network to be idling,
@@ -52,21 +52,33 @@ module Ferrum
     # @param [Float] timeout
     #   During what time we try to check idle.
     #
-    # @raise [Ferrum::TimeoutError]
+    # @return [Boolean]
     #
     # @example
     #   browser.go_to("https://example.com/")
     #   browser.at_xpath("//a[text() = 'No UI changes button']").click
-    #   browser.network.wait_for_idle
+    #   browser.network.wait_for_idle # => false
     #
-    def wait_for_idle(connections: 0, duration: 0.05, timeout: @page.browser.timeout)
+    def wait_for_idle(connections: 0, duration: 0.05, timeout: @page.timeout)
       start = Utils::ElapsedTime.monotonic_time
 
       until idle?(connections)
-        raise TimeoutError if Utils::ElapsedTime.timeout?(start, timeout)
+        return false if Utils::ElapsedTime.timeout?(start, timeout)
 
         sleep(duration)
       end
+
+      true
+    end
+
+    #
+    # Waits for network idle or raises {Ferrum::TimeoutError} error.
+    # Accepts same arguments as `wait_for_idle`.
+    #
+    # @raise [Ferrum::TimeoutError]
+    def wait_for_idle!(...)
+      result = wait_for_idle(...)
+      raise TimeoutError unless result
     end
 
     def idle?(connections = 0)
@@ -356,26 +368,24 @@ module Ferrum
       @page.on("Network.requestWillBeSent") do |params|
         request = Network::Request.new(params)
 
-        # We can build exchange in two places, here on the event or when request
-        # is interrupted. So we have to be careful when to create new one. We
-        # create new exchange only if there's no with such id or there's but
-        # it's filled with request which means this one is new but has response
-        # for a redirect. So we assign response from the params to previous
-        # exchange and build new exchange to assign this request to it.
-        exchange = select(request.id).last
-        exchange = build_exchange(request.id) unless exchange&.blank?
-
         # On redirects Chrome doesn't change `requestId` and there's no
         # `Network.responseReceived` event for such request. If there's already
         # exchange object with this id then we got redirected and params has
         # `redirectResponse` key which contains the response.
-        if params["redirectResponse"]
-          previous_exchange = select(request.id)[-2]
+        if params["redirectResponse"] && (previous_exchange = select(request.id).last)
           response = Network::Response.new(@page, params)
           response.loaded = true
           previous_exchange.response = response
         end
 
+        # We can build exchange in two places, here on the event or when request
+        # is interrupted. So we have to be careful when to create new one. We
+        # create new exchange only if there's no with such id or there's but
+        # it's filled with request which means this one is new but has response
+        # for a redirect. So we assign response from the params to previous
+        # exchange and build new exchange to assign this request to it.
+        exchange = select(request.id).last
+        exchange = build_exchange(request.id) unless exchange&.blank?
         exchange.request = request
 
         @exchange = exchange if exchange.navigation_request?(@page.main_frame.id)
@@ -385,19 +395,19 @@ module Ferrum
     def subscribe_response_received
       @page.on("Network.responseReceived") do |params|
         exchange = select(params["requestId"]).last
+        next unless exchange
 
-        if exchange
-          response = Network::Response.new(@page, params)
-          exchange.response = response
-        end
+        response = Network::Response.new(@page, params)
+        exchange.response = response
       end
     end
 
     def subscribe_loading_finished
       @page.on("Network.loadingFinished") do |params|
-        response = select(params["requestId"]).last&.response
+        exchange = select(params["requestId"]).last
+        next unless exchange
 
-        if response
+        if (response = exchange.response)
           response.loaded = true
           response.body_size = params["encodedDataLength"]
         end
@@ -407,8 +417,9 @@ module Ferrum
     def subscribe_loading_failed
       @page.on("Network.loadingFailed") do |params|
         exchange = select(params["requestId"]).last
-        exchange.error ||= Network::Error.new
+        next unless exchange
 
+        exchange.error ||= Network::Error.new
         exchange.error.id = params["requestId"]
         exchange.error.type = params["type"]
         exchange.error.error_text = params["errorText"]
@@ -422,8 +433,9 @@ module Ferrum
         entry = params["entry"] || {}
         if entry["source"] == "network" && entry["level"] == "error"
           exchange = select(entry["networkRequestId"]).last
-          exchange.error ||= Network::Error.new
+          next unless exchange
 
+          exchange.error ||= Network::Error.new
           exchange.error.id = entry["networkRequestId"]
           exchange.error.url = entry["url"]
           exchange.error.description = entry["text"]

data/lib/ferrum/node.rb

@@ -217,6 +217,17 @@ module Ferrum
         .each_with_object({}) { |style, memo| memo.merge!(style["name"] => style["value"]) }
     end
 
+    def remove
+      page.command("DOM.removeNode", nodeId: node_id)
+    end
+
+    def exists?
+      page.command("DOM.resolveNode", nodeId: node_id)
+      true
+    rescue Ferrum::NodeNotFoundError
+      false
+    end
+
     private
 
     def bounding_rect_coordinates

data/lib/ferrum/page/frames.rb

@@ -16,8 +16,8 @@ module Ferrum
       # @return [Array<Frame>]
       #
       # @example
-      #   browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
-      #   browser.frames # =>
+      #   page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+      #   page.frames # =>
       #   # [
       #   #   #<Ferrum::Frame
       #   #     @id="C6D104CE454A025FBCF22B98DE612B12"
@@ -36,10 +36,10 @@ module Ferrum
       end
 
       #
-      # Find frame by given options.
+      # Find a frame by given params.
       #
       # @param [String] id
-      #   Unique frame's id that browser provides.
+      #   Unique frame's id that page provides.
       #
       # @param [String] name
       #   Frame's name if there's one.
@@ -51,7 +51,7 @@ module Ferrum
       #   The matching frame.
       #
       # @example
-      #   browser.frame_by(id: "C6D104CE454A025FBCF22B98DE612B12")
+      #   page.frame_by(id: "C6D104CE454A025FBCF22B98DE612B12")
       #
       def frame_by(id: nil, name: nil, execution_id: nil)
         if id
@@ -60,8 +60,6 @@ module Ferrum
           frames.find { |f| f.name == name }
         elsif execution_id
           frames.find { |f| f.execution_id == execution_id }
-        else
-          raise ArgumentError
         end
       end
 
@@ -130,11 +128,11 @@ module Ferrum
           # node will change the id and all subsequent nodes have to change id too.
           if @main_frame.id == params["frameId"]
             @event.set if idling?
-            document_node_id
+            document_node_id(async: true)
           end
 
           frame = @frames[params["frameId"]]
-          frame.state = :stopped_loading
+          frame&.state = :stopped_loading
 
           @event.set if idling?
         end

data/lib/ferrum/page/screenshot.rb

@@ -5,6 +5,12 @@ require "ferrum/rgba"
 module Ferrum
   class Page
     module Screenshot
+      FULL_WARNING = "Ignoring :selector or :area in #screenshot since full: true was given at %s"
+      AREA_WARNING = "Ignoring :area in #screenshot since selector: was given at %s"
+
+      DEFAULT_SCREENSHOT_FORMAT = "png"
+      SUPPORTED_SCREENSHOT_FORMAT = %w[png jpeg jpg webp].freeze
+
       DEFAULT_PDF_OPTIONS = {
         landscape: false,
         paper_width: 8.5,
@@ -38,7 +44,7 @@ module Ferrum
       # @option opts [:base64, :binary] :encoding
       #   The encoding the image should be returned in.
       #
-      # @option opts ["jpeg", "png"] :format
+      # @option opts ["jpeg", "jpg", "png", "webp"] :format
       #   The format the image should be returned in.
       #
       # @option opts [Integer] :quality
@@ -50,6 +56,9 @@ module Ferrum
       # @option opts [String] :selector
       #   CSS selector for the given element.
       #
+      # @option opts [Hash] :area
+      #   x, y, width, height to screenshot an area.
+      #
       # @option opts [Float] :scale
       #   Zoom in/out.
       #
@@ -57,19 +66,22 @@ module Ferrum
       #   Sets the background color.
       #
       # @example
-      #   browser.go_to("https://google.com/")
+      #   page.go_to("https://google.com/")
       #
       # @example Save on the disk in PNG:
-      #   browser.screenshot(path: "google.png") # => 134660
+      #   page.screenshot(path: "google.png") # => 134660
       #
       # @example Save on the disk in JPG:
-      #   browser.screenshot(path: "google.jpg") # => 30902
+      #   page.screenshot(path: "google.jpg") # => 30902
+      #
+      # @example Save to Base64 in WebP with reduce quality:
+      #   page.screenshot(format: "webp", quality: 60) # "iVBORw0KGgoAAAANS...
       #
       # @example Save to Base64 the whole page not only viewport and reduce quality:
-      #   browser.screenshot(full: true, quality: 60) # "iVBORw0KGgoAAAANS...
+      #   page.screenshot(full: true, format: "jpeg", quality: 60) # "iVBORw0KGgoAAAANS...
       #
       # @example Save with specific background color:
-      #   browser.screenshot(background_color: Ferrum::RGBA.new(0, 0, 0, 0.0))
+      #   page.screenshot(background_color: Ferrum::RGBA.new(0, 0, 0, 0.0))
       #
       def screenshot(**opts)
         path, encoding = common_options(**opts)
@@ -113,9 +125,9 @@ module Ferrum
       #   can pass.
       #
       # @example
-      #   browser.go_to("https://google.com/")
+      #   page.go_to("https://google.com/")
       #   # Save to disk as a PDF
-      #   browser.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true
+      #   page.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true
       #
       def pdf(**opts)
         path, encoding = common_options(**opts)
@@ -131,8 +143,8 @@ module Ferrum
       #   The path to save a file on the disk.
       #
       # @example
-      #   browser.go_to("https://google.com/")
-      #   browser.mhtml(path: "google.mhtml") # => 87742
+      #   page.go_to("https://google.com/")
+      #   page.mhtml(path: "google.mhtml") # => 87742
       #
       def mhtml(path: nil)
         data = command("Page.captureSnapshot", format: :mhtml).fetch("data")
@@ -198,45 +210,59 @@ module Ferrum
         screenshot_options.merge!(quality: quality) if quality
         screenshot_options.merge!(format: format)
 
-        clip = area_options(options[:full], options[:selector], scale)
+        clip = area_options(options[:full], options[:selector], scale, options[:area])
         screenshot_options.merge!(clip: clip) if clip
 
         screenshot_options
       end
 
       def format_options(format, path, quality)
-        format ||= path ? File.extname(path).delete(".") : "png"
+        if !format && path # try to infer from path
+          extension = File.extname(path).delete(".").downcase
+          format = extension unless extension.empty?
+        end
+
+        format ||= DEFAULT_SCREENSHOT_FORMAT
+        format = format.to_s
+        raise Ferrum::InvalidScreenshotFormatError, format unless SUPPORTED_SCREENSHOT_FORMAT.include?(format)
+
         format = "jpeg" if format == "jpg"
-        raise "Not supported options `:format` #{format}. jpeg | png" if format !~ /jpeg|png/i
 
-        quality ||= 75 if format == "jpeg"
+        # Chrome supports screenshot qualities for JPEG and WebP
+        quality ||= 75 if format != "png"
 
         [format, quality]
       end
 
-      def area_options(full, selector, scale)
-        message = "Ignoring :selector in #screenshot since full: true was given at #{caller(1..1).first}"
-        warn(message) if full && selector
+      def area_options(full, selector, scale, area = nil)
+        warn(FULL_WARNING % caller(1..1).first) if full && (selector || area)
+        warn(AREA_WARNING % caller(1..1).first) if selector && area
 
         clip = if full
-                 width, height = document_size
-                 { x: 0, y: 0, width: width, height: height, scale: scale } if width.positive? && height.positive?
+                 full_window_area || viewport_area
                elsif selector
-                 bounding_rect(selector).merge(scale: scale)
+                 bounding_rect(selector)
+               elsif area
+                 area
+               else
+                 viewport_area
                end
 
-        if scale != 1
-          unless clip
-            width, height = viewport_size
-            clip = { x: 0, y: 0, width: width, height: height }
-          end
-
-          clip.merge!(scale: scale)
-        end
+        clip.merge!(scale: scale)
 
         clip
       end
 
+      def full_window_area
+        width, height = document_size
+        { x: 0, y: 0, width: width, height: height } if width.positive? && height.positive?
+      end
+
+      def viewport_area
+        width, height = viewport_size
+        { x: 0, y: 0, width: width, height: height }
+      end
+
       def bounding_rect(selector)
         rect = evaluate_async(%(
           const rect = document