ferrum 0.12 → 0.14

data/lib/ferrum/network/request_params.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Ferrum
+  class Network
+    #
+    # Common methods used by both {Request} and {InterceptedRequest}.
+    #
+    module RequestParams
+      #
+      # The URL for the request.
+      #
+      # @return [String]
+      #
+      def url
+        @request["url"]
+      end
+
+      #
+      # The URL fragment for the request.
+      #
+      # @return [String, nil]
+      #
+      def url_fragment
+        @request["urlFragment"]
+      end
+
+      #
+      # The request method.
+      #
+      # @return [String]
+      #
+      def method
+        @request["method"]
+      end
+
+      #
+      # The request headers.
+      #
+      # @return [Hash{String => String}]
+      #
+      def headers
+        @request["headers"]
+      end
+
+      #
+      # The optional HTTP `POST` form data.
+      #
+      # @return [String, nil]
+      #   The HTTP `POST` form data.
+      #
+      def post_data
+        @request["postData"]
+      end
+      alias body post_data
+    end
+  end
+end

data/lib/ferrum/network/response.rb

@@ -2,43 +2,110 @@
 
 module Ferrum
   class Network
+    #
+    # Represents a [Network.Response](https://chromedevtools.github.io/devtools-protocol/1-3/Network/#type-Response)
+    # object.
+    #
     class Response
-      attr_reader :body_size, :params
+      # The response body size.
+      #
+      # @return [Integer, nil]
+      attr_reader :body_size
 
+      # The parsed JSON attributes for the [Network.Response](https://chromedevtools.github.io/devtools-protocol/1-3/Network/#type-Response)
+      # object.
+      #
+      # @return [Hash{String => Object}]
+      attr_reader :params
+
+      # The response is fully loaded by the browser.
+      #
+      # @return [Boolean]
+      attr_writer :loaded
+
+      #
+      # Initializes the responses object.
+      #
+      # @param [Page] page
+      #   The page associated with the network response.
+      #
+      # @param [Hash{String => Object}] params
+      #   The parsed JSON attributes for the [Network.Response](https://chromedevtools.github.io/devtools-protocol/1-3/Network/#type-Response)
+      #
       def initialize(page, params)
         @page = page
         @params = params
         @response = params["response"] || params["redirectResponse"]
       end
 
+      #
+      # The request ID associated with the response.
+      #
+      # @return [String]
+      #
       def id
         @params["requestId"]
       end
 
+      #
+      # The URL of the response.
+      #
+      # @return [String]
+      #
       def url
         @response["url"]
       end
 
+      #
+      # The HTTP status of the response.
+      #
+      # @return [Integer]
+      #
       def status
         @response["status"]
       end
 
+      #
+      # The HTTP status text.
+      #
+      # @return [String]
+      #
       def status_text
         @response["statusText"]
       end
 
+      #
+      # The headers of the response.
+      #
+      # @return [Hash{String => String}]
+      #
       def headers
         @response["headers"]
       end
 
+      #
+      # The total size in bytes of the response.
+      #
+      # @return [Integer]
+      #
       def headers_size
         @response["encodedDataLength"]
       end
 
+      #
+      # The resource type of the response.
+      #
+      # @return [String]
+      #
       def type
         @params["type"]
       end
 
+      #
+      # The `Content-Type` header value of the response.
+      #
+      # @return [String, nil]
+      #
       def content_type
         @content_type ||= headers.find { |k, _| k.downcase == "content-type" }&.last&.sub(/;.*\z/, "")
       end
@@ -52,26 +119,61 @@ module Ferrum
         @body_size = size - headers_size
       end
 
+      #
+      # The response body.
+      #
+      # @return [String]
+      #
       def body
         @body ||= begin
-          body, encoded = @page
-                          .command("Network.getResponseBody", requestId: id)
-                          .values_at("body", "base64Encoded")
+          body, encoded = @page.command("Network.getResponseBody", requestId: id)
+                               .values_at("body", "base64Encoded")
           encoded ? Base64.decode64(body) : body
         end
       end
 
+      #
+      # @return [Boolean]
+      #
       def main?
         @page.network.response == self
       end
 
+      # The response is fully loaded by the browser or not.
+      #
+      # @return [Boolean]
+      def loaded?
+        @loaded
+      end
+
+      # Whether the response is a redirect.
+      #
+      # @return [Boolean]
+      def redirect?
+        params.key?("redirectResponse")
+      end
+
+      #
+      # Compares the response's ID to another response's ID.
+      #
+      # @return [Boolean]
+      #   Indicates whether the response has the same ID as the other response
+      #   object.
+      #
       def ==(other)
         id == other.id
       end
 
+      #
+      # Inspects the response object.
+      #
+      # @return [String]
+      #
       def inspect
         %(#<#{self.class} @params=#{@params.inspect} @response=#{@response.inspect}>)
       end
+
+      alias to_h params
     end
   end
 end

data/lib/ferrum/network.rb

@@ -11,14 +11,25 @@ module Ferrum
   class Network
     CLEAR_TYPE = %i[traffic cache].freeze
     AUTHORIZE_TYPE = %i[server proxy].freeze
-    RESOURCE_TYPES = %w[Document Stylesheet Image Media Font Script TextTrack
-                        XHR Fetch EventSource WebSocket Manifest
-                        SignedExchange Ping CSPViolationReport Other].freeze
+    REQUEST_STAGES = %i[Request Response].freeze
+    RESOURCE_TYPES = %i[Document Stylesheet Image Media Font Script TextTrack
+                        XHR Fetch Prefetch EventSource WebSocket Manifest
+                        SignedExchange Ping CSPViolationReport Preflight Other].freeze
     AUTHORIZE_BLOCK_MISSING = "Block is missing, call `authorize(...) { |r| r.continue } " \
                               "or subscribe to `on(:request)` events before calling it"
     AUTHORIZE_TYPE_WRONG = ":type should be in #{AUTHORIZE_TYPE}"
     ALLOWED_CONNECTION_TYPE = %w[none cellular2g cellular3g cellular4g bluetooth ethernet wifi wimax other].freeze
 
+    # Network traffic.
+    #
+    # @return [Array<Exchange>]
+    #   Returns all information about network traffic as {Exchange}
+    #   instance which in general is a wrapper around `request`, `response` and
+    #   `error`.
+    #
+    # @example
+    #   browser.go_to("https://github.com/")
+    #   browser.network.traffic # => [#<Ferrum::Network::Exchange, ...]
     attr_reader :traffic
 
     def initialize(page)
@@ -29,6 +40,25 @@ module Ferrum
       @whitelist = nil
     end
 
+    #
+    # Waits for network idle or raises {Ferrum::TimeoutError} error.
+    #
+    # @param [Integer] connections
+    #   how many connections are allowed for network to be idling,
+    #
+    # @param [Float] duration
+    #   Sleep for given amount of time and check again.
+    #
+    # @param [Float] timeout
+    #   During what time we try to check idle.
+    #
+    # @raise [Ferrum::TimeoutError]
+    #
+    # @example
+    #   browser.go_to("https://example.com/")
+    #   browser.at_xpath("//a[text() = 'No UI changes button']").click
+    #   browser.network.wait_for_idle
+    #
     def wait_for_idle(connections: 0, duration: 0.05, timeout: @page.browser.timeout)
       start = Utils::ElapsedTime.monotonic_time
 
@@ -55,18 +85,61 @@ module Ferrum
       total_connections - finished_connections
     end
 
+    #
+    # Page request of the main frame.
+    #
+    # @return [Request]
+    #
+    # @example
+    #   browser.go_to("https://github.com/")
+    #   browser.network.request # => #<Ferrum::Network::Request...
+    #
     def request
       @exchange&.request
     end
 
+    #
+    # Page response of the main frame.
+    #
+    # @return [Response, nil]
+    #
+    # @example
+    #   browser.go_to("https://github.com/")
+    #   browser.network.response # => #<Ferrum::Network::Response...
+    #
     def response
       @exchange&.response
     end
 
+    #
+    # Contains the status code of the main page response (e.g., 200 for a
+    # success). This is just a shortcut for `response.status`.
+    #
+    # @return [Integer, nil]
+    #
+    # @example
+    #   browser.go_to("https://github.com/")
+    #   browser.network.status # => 200
+    #
     def status
       response&.status
     end
 
+    #
+    # Clear browser's cache or collected traffic.
+    #
+    # @param [:traffic, :cache] type
+    #   The type of traffic to clear.
+    #
+    # @return [true]
+    #
+    # @example
+    #   traffic = browser.network.traffic # => []
+    #   browser.go_to("https://github.com/")
+    #   traffic.size # => 51
+    #   browser.network.clear(:traffic)
+    #   traffic.size # => 0
+    #
     def clear(type)
       raise ArgumentError, ":type should be in #{CLEAR_TYPE}" unless CLEAR_TYPE.include?(type)
 
@@ -91,13 +164,71 @@ module Ferrum
     end
     alias allowlist= whitelist=
 
-    def intercept(pattern: "*", resource_type: nil)
+    #
+    # Set request interception for given options. This method is only sets
+    # request interception, you should use `on` callback to catch requests and
+    # abort or continue them.
+    #
+    # @param [String] pattern
+    #
+    # @param [Symbol, nil] resource_type
+    #   One of the [resource types](https://chromedevtools.github.io/devtools-protocol/tot/Network#type-ResourceType)
+    #
+    # @example
+    #   browser = Ferrum::Browser.new
+    #   browser.network.intercept
+    #   browser.on(:request) do |request|
+    #     if request.match?(/bla-bla/)
+    #       request.abort
+    #     elsif request.match?(/lorem/)
+    #       request.respond(body: "Lorem ipsum")
+    #     else
+    #       request.continue
+    #     end
+    #   end
+    #   browser.go_to("https://google.com")
+    #
+    def intercept(pattern: "*", resource_type: nil, request_stage: nil, handle_auth_requests: true)
       pattern = { urlPattern: pattern }
-      pattern[:resourceType] = resource_type if resource_type && RESOURCE_TYPES.include?(resource_type.to_s)
 
-      @page.command("Fetch.enable", handleAuthRequests: true, patterns: [pattern])
+      if resource_type && RESOURCE_TYPES.none?(resource_type.to_sym)
+        raise ArgumentError, "Unknown resource type '#{resource_type}' must be #{RESOURCE_TYPES.join(' | ')}"
+      end
+
+      if request_stage && REQUEST_STAGES.none?(request_stage.to_sym)
+        raise ArgumentError, "Unknown request stage '#{request_stage}' must be #{REQUEST_STAGES.join(' | ')}"
+      end
+
+      pattern[:resourceType] = resource_type if resource_type
+      pattern[:requestStage] = request_stage if request_stage
+      @page.command("Fetch.enable", patterns: [pattern], handleAuthRequests: handle_auth_requests)
     end
 
+    #
+    # Sets HTTP Basic-Auth credentials.
+    #
+    # @param [String] user
+    #   The username to send.
+    #
+    # @param [String] password
+    #   The password to send.
+    #
+    # @param [:server, :proxy] type
+    #   Specifies whether the credentials are for a website or a proxy.
+    #
+    # @yield [request]
+    #   The given block will be passed each authenticated request and can allow
+    #   or deny the request.
+    #
+    # @yieldparam [Request] request
+    #   An HTTP request.
+    #
+    # @example
+    #   browser.network.authorize(user: "login", password: "pass") { |req| req.continue }
+    #   browser.go_to("http://example.com/authenticated")
+    #   puts browser.network.status # => 200
+    #   puts browser.body # => Welcome, authenticated client
+    #
     def authorize(user:, password:, type: :server, &block)
       raise ArgumentError, AUTHORIZE_TYPE_WRONG unless AUTHORIZE_TYPE.include?(type)
       raise ArgumentError, AUTHORIZE_BLOCK_MISSING if !block_given? && !@page.subscribed?("Fetch.requestPaused")
@@ -151,6 +282,37 @@ module Ferrum
       Network::Exchange.new(@page, id).tap { |e| @traffic << e }
     end
 
+    #
+    # Activates emulation of network conditions.
+    #
+    # @param [Boolean] offline
+    #   Emulate internet disconnection,
+    #
+    # @param [Integer] latency
+    #   Minimum latency from request sent to response headers received (ms).
+    #
+    # @param [Integer] download_throughput
+    #   Maximal aggregated download throughput (bytes/sec).
+    #
+    # @param [Integer] upload_throughput
+    #   Maximal aggregated upload throughput (bytes/sec).
+    #
+    # @param [String, nil] connection_type
+    #   Connection type if known:
+    #   * `"none"`
+    #   * `"cellular2g"`
+    #   * `"cellular3g"`
+    #   * `"cellular4g"`
+    #   * `"bluetooth"`
+    #   * `"ethernet"`
+    #   * `"wifi"`
+    #   * `"wimax"`
+    #   * `"other"`
+    #
+    # @example
+    #   browser.network.emulate_network_conditions(connection_type: "cellular2g")
+    #   browser.go_to("https://github.com/")
+    #
     def emulate_network_conditions(offline: false, latency: 0,
                                    download_throughput: -1, upload_throughput: -1,
                                    connection_type: nil)
@@ -166,10 +328,28 @@ module Ferrum
       true
     end
 
+    #
+    # Activates offline mode for a page.
+    #
+    # @example
+    #   browser.network.offline_mode
+    #   browser.go_to("https://github.com/")
+    #     # => Request to https://github.com/ failed (net::ERR_INTERNET_DISCONNECTED) (Ferrum::StatusError)
+    #
     def offline_mode
       emulate_network_conditions(offline: true, latency: 0, download_throughput: 0, upload_throughput: 0)
     end
 
+    #
+    # Toggles ignoring cache for each request. If true, cache will not be used.
+    #
+    # @example
+    #   browser.network.cache(disable: true)
+    #
+    def cache(disable:)
+      @page.command("Network.setCacheDisabled", cacheDisabled: disable)
+    end
+
     private
 
     def subscribe_request_will_be_sent
@@ -192,6 +372,7 @@ module Ferrum
         if params["redirectResponse"]
           previous_exchange = select(request.id)[-2]
           response = Network::Response.new(@page, params)
+          response.loaded = true
           previous_exchange.response = response
         end
 
@@ -214,8 +395,12 @@ module Ferrum
 
     def subscribe_loading_finished
       @page.on("Network.loadingFinished") do |params|
-        exchange = select(params["requestId"]).last
-        exchange.response.body_size = params["encodedDataLength"] if exchange&.response
+        response = select(params["requestId"]).last&.response
+
+        if response
+          response.loaded = true
+          response.body_size = params["encodedDataLength"]
+        end
       end
     end
 

data/lib/ferrum/node.rb

@@ -88,6 +88,26 @@ module Ferrum
       raise NotImplementedError
     end
 
+    def scroll_into_view
+      tap { page.command("DOM.scrollIntoViewIfNeeded", nodeId: node_id) }
+    end
+
+    def in_viewport?(of: nil)
+      function = <<~JS
+        function(element, scope) {
+          const rect = element.getBoundingClientRect();
+          const [height, width] = scope
+            ? [scope.offsetHeight, scope.offsetWidth]
+            : [window.innerHeight, window.innerWidth];
+          return rect.top >= 0 &&
+           rect.left >= 0 &&
+           rect.bottom <= height &&
+           rect.right <= width;
+        }
+      JS
+      page.evaluate_func(function, self, of)
+    end
+
     def select_file(value)
       page.command("DOM.setFileInputFiles", slowmoable: true, nodeId: node_id, files: Array(value))
     end
@@ -208,7 +228,7 @@ module Ferrum
 
     def content_quads
       quads = page.command("DOM.getContentQuads", nodeId: node_id)["quads"]
-      raise CoordinatesNotFoundError, "Node is either not visible or not an HTMLElement" if quads.size.zero?
+      raise CoordinatesNotFoundError, "Node is either not visible or not an HTMLElement" if quads.empty?
 
       quads
     end

data/lib/ferrum/page/animation.rb

@@ -3,10 +3,26 @@
 module Ferrum
   class Page
     module Animation
+      #
+      # Returns playback rate for CSS animations, defaults to `1`.
+      #
+      # @return [Integer]
+      #
       def playback_rate
         command("Animation.getPlaybackRate")["playbackRate"]
       end
 
+      #
+      # Sets playback rate of CSS animations.
+      #
+      # @param [Integer] value
+      #
+      # @example
+      #   browser = Ferrum::Browser.new
+      #   browser.playback_rate = 2000
+      #   browser.go_to("https://google.com")
+      #   browser.playback_rate # => 2000
+      #
       def playback_rate=(value)
         command("Animation.setPlaybackRate", playbackRate: value)
       end