ferrum 0.11 → 0.13

data/lib/ferrum/network.rb

@@ -14,20 +14,56 @@ module Ferrum
     RESOURCE_TYPES = %w[Document Stylesheet Image Media Font Script TextTrack
                         XHR Fetch EventSource WebSocket Manifest
                         SignedExchange Ping CSPViolationReport 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)
       @page = page
       @traffic = []
       @exchange = nil
+      @blacklist = nil
+      @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 = Ferrum.monotonic_time
+      start = Utils::ElapsedTime.monotonic_time
 
       until idle?(connections)
-        raise TimeoutError if Ferrum.timeout?(start, timeout)
+        raise TimeoutError if Utils::ElapsedTime.timeout?(start, timeout)
+
         sleep(duration)
       end
     end
@@ -48,22 +84,63 @@ 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)
-      unless CLEAR_TYPE.include?(type)
-        raise ArgumentError, ":type should be in #{CLEAR_TYPE}"
-      end
+      raise ArgumentError, ":type should be in #{CLEAR_TYPE}" unless CLEAR_TYPE.include?(type)
 
       if type == :traffic
         @traffic.clear
@@ -74,23 +151,77 @@ module Ferrum
       true
     end
 
+    def blacklist=(patterns)
+      @blacklist = Array(patterns)
+      blacklist_subscribe
+    end
+    alias blocklist= blacklist=
+
+    def whitelist=(patterns)
+      @whitelist = Array(patterns)
+      whitelist_subscribe
+    end
+    alias allowlist= whitelist=
+
+    #
+    # 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)
       pattern = { urlPattern: pattern }
-      if resource_type && RESOURCE_TYPES.include?(resource_type.to_s)
-        pattern[:resourceType] = resource_type
-      end
+      pattern[:resourceType] = resource_type if resource_type && RESOURCE_TYPES.include?(resource_type.to_s)
 
       @page.command("Fetch.enable", handleAuthRequests: true, patterns: [pattern])
     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)
-      unless AUTHORIZE_TYPE.include?(type)
-        raise ArgumentError, ":type should be in #{AUTHORIZE_TYPE}"
-      end
-
-      if !block_given? && !@page.subscribed?("Fetch.requestPaused")
-        raise ArgumentError, "Block is missing, call `authorize(...) { |r| r.continue } or subscribe to `on(:request)` events before calling it"
-      end
+      raise ArgumentError, AUTHORIZE_TYPE_WRONG unless AUTHORIZE_TYPE.include?(type)
+      raise ArgumentError, AUTHORIZE_BLOCK_MISSING if !block_given? && !@page.subscribed?("Fetch.requestPaused")
 
       @authorized_ids ||= {}
       @authorized_ids[type] ||= []
@@ -116,6 +247,92 @@ module Ferrum
     end
 
     def subscribe
+      subscribe_request_will_be_sent
+      subscribe_response_received
+      subscribe_loading_finished
+      subscribe_loading_failed
+      subscribe_log_entry_added
+    end
+
+    def authorized_response(ids, request_id, username, password)
+      if ids.include?(request_id)
+        { response: "CancelAuth" }
+      elsif username && password
+        { response: "ProvideCredentials",
+          username: username,
+          password: password }
+      end
+    end
+
+    def select(request_id)
+      @traffic.select { |e| e.id == request_id }
+    end
+
+    def build_exchange(id)
+      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)
+      params = {
+        offline: offline, latency: latency,
+        downloadThroughput: download_throughput,
+        uploadThroughput: upload_throughput
+      }
+
+      params[:connectionType] = connection_type if connection_type && ALLOWED_CONNECTION_TYPE.include?(connection_type)
+
+      @page.command("Network.emulateNetworkConditions", **params)
+      true
+    end
+
+    #
+    # Activates offline mode for a page.
+    #
+    # @example
+    #   browser.network.offline_mode
+    #   browser.go_to("https://github.com/") # => Ferrum::StatusError (Request to https://github.com/ failed to reach
+    #   server, check DNS and server status)
+    #
+    def offline_mode
+      emulate_network_conditions(offline: true, latency: 0, download_throughput: 0, upload_throughput: 0)
+    end
+
+    private
+
+    def subscribe_request_will_be_sent
       @page.on("Network.requestWillBeSent") do |params|
         request = Network::Request.new(params)
 
@@ -140,25 +357,29 @@ module Ferrum
 
         exchange.request = request
 
-        if exchange.navigation_request?(@page.main_frame.id)
-          @exchange = exchange
-        end
+        @exchange = exchange if exchange.navigation_request?(@page.main_frame.id)
       end
+    end
 
+    def subscribe_response_received
       @page.on("Network.responseReceived") do |params|
-        if exchange = select(params["requestId"]).last
+        exchange = select(params["requestId"]).last
+
+        if exchange
           response = Network::Response.new(@page, params)
           exchange.response = response
         end
       end
+    end
 
+    def subscribe_loading_finished
       @page.on("Network.loadingFinished") do |params|
         exchange = select(params["requestId"]).last
-        if exchange && exchange.response
-          exchange.response.body_size = params["encodedDataLength"]
-        end
+        exchange.response.body_size = params["encodedDataLength"] if exchange&.response
       end
+    end
 
+    def subscribe_loading_failed
       @page.on("Network.loadingFailed") do |params|
         exchange = select(params["requestId"]).last
         exchange.error ||= Network::Error.new
@@ -169,7 +390,9 @@ module Ferrum
         exchange.error.monotonic_time = params["timestamp"]
         exchange.error.canceled = params["canceled"]
       end
+    end
 
+    def subscribe_log_entry_added
       @page.on("Log.entryAdded") do |params|
         entry = params["entry"] || {}
         if entry["source"] == "network" && entry["level"] == "error"
@@ -184,24 +407,50 @@ module Ferrum
       end
     end
 
-    def authorized_response(ids, request_id, username, password)
-      if ids.include?(request_id)
-        { response: "CancelAuth" }
-      elsif username && password
-        { response: "ProvideCredentials",
-          username: username,
-          password: password }
-      else
-        { response: "CancelAuth" }
+    def blacklist_subscribe
+      return unless blacklist?
+      raise ArgumentError, "You can't use blacklist along with whitelist" if whitelist?
+
+      @blacklist_subscribe ||= begin
+        intercept
+
+        @page.on(:request) do |request|
+          if @blacklist.any? { |p| request.match?(p) }
+            request.abort
+          else
+            request.continue
+          end
+        end
+
+        true
       end
     end
 
-    def select(request_id)
-      @traffic.select { |e| e.id == request_id }
+    def whitelist_subscribe
+      return unless whitelist?
+      raise ArgumentError, "You can't use whitelist along with blacklist" if blacklist?
+
+      @whitelist_subscribe ||= begin
+        intercept
+
+        @page.on(:request) do |request|
+          if @whitelist.any? { |p| request.match?(p) }
+            request.continue
+          else
+            request.abort
+          end
+        end
+
+        true
+      end
     end
 
-    def build_exchange(id)
-      Network::Exchange.new(@page, id).tap { |e| @traffic << e }
+    def blacklist?
+      Array(@blacklist).any?
+    end
+
+    def whitelist?
+      Array(@whitelist).any?
     end
   end
 end

data/lib/ferrum/node.rb

@@ -10,7 +10,8 @@ module Ferrum
     def initialize(frame, target_id, node_id, description)
       @page = frame.page
       @target_id = target_id
-      @node_id, @description = node_id, description
+      @node_id = node_id
+      @description = description
       @tag_name = description["nodeName"].downcase
     end
 
@@ -38,15 +39,16 @@ module Ferrum
     end
 
     def wait_for_stop_moving(delay: MOVING_WAIT_DELAY, attempts: MOVING_WAIT_ATTEMPTS)
-      Ferrum.with_attempts(errors: NodeMovingError, max: attempts, wait: 0) do
-        previous, current = get_content_quads_with(delay: delay)
+      Utils::Attempt.with_retry(errors: NodeMovingError, max: attempts, wait: 0) do
+        previous, current = content_quads_with(delay: delay)
         raise NodeMovingError.new(self, previous, current) if previous != current
+
         current
       end
     end
 
     def moving?(delay: MOVING_WAIT_DELAY)
-      previous, current = get_content_quads_with(delay: delay)
+      previous, current = content_quads_with(delay: delay)
       previous == current
     end
 
@@ -122,17 +124,52 @@ module Ferrum
     def property(name)
       evaluate("this['#{name}']")
     end
+    alias [] property
 
     def attribute(name)
       evaluate("this.getAttribute('#{name}')")
     end
 
+    def selected
+      function = <<~JS
+        function(element) {
+          if (element.nodeName.toLowerCase() !== 'select') {
+            throw new Error('Element is not a <select> element.');
+          }
+          return Array.from(element).filter(option => option.selected);
+        }
+      JS
+      page.evaluate_func(function, self, on: self)
+    end
+
+    def select(*values, by: :value)
+      tap do
+        function = <<~JS
+          function(element, values, by) {
+            if (element.nodeName.toLowerCase() !== 'select') {
+              throw new Error('Element is not a <select> element.');
+            }
+            const options = Array.from(element.options);
+            element.value = undefined;
+            for (const option of options) {
+              option.selected = values.some((value) => option[by] === value);
+              if (option.selected && !element.multiple) break;
+            }
+            element.dispatchEvent(new Event('input', { bubbles: true }));
+            element.dispatchEvent(new Event('change', { bubbles: true }));
+          }
+        JS
+        page.evaluate_func(function, self, values.flatten, by, on: self)
+      end
+    end
+
     def evaluate(expression)
       page.evaluate_on(node: self, expression: expression)
     end
 
     def ==(other)
       return false unless other.is_a?(Node)
+
       # We compare backendNodeId because once nodeId is sent to frontend backend
       # never returns same nodeId sending 0. In other words frontend is
       # responsible for keeping track of node ids.
@@ -147,30 +184,39 @@ module Ferrum
       points = wait_for_stop_moving.map { |q| to_points(q) }.first
       get_position(points, x, y, position)
     rescue CoordinatesNotFoundError
-      x, y = get_bounding_rect_coordinates
-      raise if x == 0 && y == 0
+      x, y = bounding_rect_coordinates
+      raise if x.zero? && y.zero?
+
       [x, y]
     end
 
+    # Returns a hash of the computed styles for the node
+    def computed_style
+      page
+        .command("CSS.getComputedStyleForNode", nodeId: node_id)["computedStyle"]
+        .each_with_object({}) { |style, memo| memo.merge!(style["name"] => style["value"]) }
+    end
+
     private
 
-    def get_bounding_rect_coordinates
+    def bounding_rect_coordinates
       evaluate <<~JS
         [this.getBoundingClientRect().left + window.pageXOffset + (this.offsetWidth / 2),
          this.getBoundingClientRect().top + window.pageYOffset + (this.offsetHeight / 2)]
       JS
     end
 
-    def get_content_quads
+    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 == 0
+      raise CoordinatesNotFoundError, "Node is either not visible or not an HTMLElement" if quads.size.zero?
+
       quads
     end
 
-    def get_content_quads_with(delay: MOVING_WAIT_DELAY)
-      previous = get_content_quads
+    def content_quads_with(delay: MOVING_WAIT_DELAY)
+      previous = content_quads
       sleep(delay)
-      current = get_content_quads
+      current = content_quads
       [previous, current]
     end
 
@@ -182,28 +228,28 @@ module Ferrum
         x = point[:x] + offset_x.to_i
         y = point[:y] + offset_y.to_i
       else
-        x, y = points.inject([0, 0]) do |memo, point|
-          [memo[0] + point[:x],
-           memo[1] + point[:y]]
+        x, y = points.inject([0, 0]) do |memo, coordinate|
+          [memo[0] + coordinate[:x],
+           memo[1] + coordinate[:y]]
         end
 
-        x = x / 4
-        y = y / 4
+        x /= 4
+        y /= 4
       end
 
       if offset_x && offset_y && position == :center
-        x = x + offset_x.to_i
-        y = y + offset_y.to_i
+        x += offset_x.to_i
+        y += offset_y.to_i
       end
 
       [x, y]
     end
 
     def to_points(quad)
-      [{x: quad[0], y: quad[1]},
-       {x: quad[2], y: quad[3]},
-       {x: quad[4], y: quad[5]},
-       {x: quad[6], y: quad[7]}]
+      [{ x: quad[0], y: quad[1] },
+       { x: quad[2], y: quad[3] },
+       { x: quad[4], y: quad[5] },
+       { x: quad[6], y: quad[7] }]
     end
   end
 end

data/lib/ferrum/page/animation.rb

@@ -3,11 +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