ferrum 0.12 → 0.13

data/lib/ferrum/mouse.rb

@@ -10,10 +10,50 @@ module Ferrum
       @x = @y = 0
     end
 
+    #
+    # Scroll page to a given x, y coordinates.
+    #
+    # @param [Integer] top
+    #  The pixel along the horizontal axis of the document that you want
+    #  displayed in the upper left.
+    #
+    # @param [Integer] left
+    #   The pixel along the vertical axis of the document that you want
+    #   displayed in the upper left.
+    #
+    # @example
+    #   browser.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
+    #   browser.mouse.scroll_to(0, 400)
+    #
     def scroll_to(top, left)
       tap { @page.execute("window.scrollTo(#{top}, #{left})") }
     end
 
+    #
+    # Click given coordinates, fires mouse move, down and up events.
+    #
+    # @param [Integer] x
+    #
+    # @param [Integer] y
+    #
+    # @param [Float] delay
+    #   Delay between mouse down and mouse up events.
+    #
+    # @param [Float] wait
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [:left, :right] :button (:left)
+    #   The mouse button to click.
+    #
+    # @option options [Integer] :count (1)
+    #
+    # @option options [Integer] :modifiers
+    #   Bitfield for key modifiers. See`keyboard.modifiers`.
+    #
+    # @return [self]
+    #
     def click(x:, y:, delay: 0, wait: CLICK_WAIT, **options)
       move(x: x, y: y)
       down(**options)
@@ -24,14 +64,58 @@ module Ferrum
       self
     end
 
+    #
+    # Mouse down for given coordinates.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [:left, :right] :button (:left)
+    #   The mouse button to click.
+    #
+    # @option options [Integer] :count (1)
+    #
+    # @option options [Integer] :modifiers
+    #   Bitfield for key modifiers. See`keyboard.modifiers`.
+    #
+    # @return [self]
+    #
     def down(**options)
       tap { mouse_event(type: "mousePressed", **options) }
     end
 
+    #
+    # Mouse up for given coordinates.
+    #
+    # @param [Hash{Symbol => Object}] options
+    #   Additional keyword arguments.
+    #
+    # @option options [:left, :right] :button (:left)
+    #   The mouse button to click.
+    #
+    # @option options [Integer] :count (1)
+    #
+    # @option options [Integer] :modifiers
+    #   Bitfield for key modifiers. See`keyboard.modifiers`.
+    #
+    # @return [self]
+    #
     def up(**options)
       tap { mouse_event(type: "mouseReleased", **options) }
     end
 
+    #
+    # Mouse move to given x and y.
+    #
+    # @param [Integer] x
+    #
+    # @param [Integer] y
+    #
+    # @param [Integer] steps
+    #   Sends intermediate mousemove events.
+    #
+    # @return [self]
+    #
     def move(x:, y:, steps: 1)
       from_x = @x
       from_y = @y

data/lib/ferrum/network/exchange.rb

@@ -3,9 +3,38 @@
 module Ferrum
   class Network
     class Exchange
+      # ID of the request.
+      #
+      # @return String
       attr_reader :id
-      attr_accessor :intercepted_request, :request, :response, :error
 
+      # The intercepted request.
+      #
+      # @return [InterceptedRequest, nil]
+      attr_accessor :intercepted_request
+
+      # The request object.
+      #
+      # @return [Request, nil]
+      attr_accessor :request
+
+      # The response object.
+      #
+      # @return [Response, nil]
+      attr_accessor :response
+
+      # The error object.
+      #
+      # @return [Error, nil]
+      attr_accessor :error
+
+      #
+      # Initializes the network exchange.
+      #
+      # @param [Page] page
+      #
+      # @param [String] id
+      #
       def initialize(page, id)
         @id = id
         @page = page
@@ -13,35 +42,87 @@ module Ferrum
         @request = @response = @error = nil
       end
 
+      #
+      # Determines if the network exchange was caused by a page navigation
+      # event.
+      #
+      # @param [String] frame_id
+      #
+      # @return [Boolean]
+      #
       def navigation_request?(frame_id)
-        request.type?(:document) &&
-          request.frame_id == frame_id
+        request.type?(:document) && request&.frame_id == frame_id
       end
 
+      #
+      # Determines if the network exchange has a request.
+      #
+      # @return [Boolean]
+      #
       def blank?
         !request
       end
 
+      #
+      # Determines if the request was intercepted and blocked.
+      #
+      # @return [Boolean]
+      #
       def blocked?
         intercepted? && intercepted_request.status?(:aborted)
       end
 
+      #
+      # Determines if the request was blocked, a response was returned, or if an
+      # error occurred.
+      #
+      # @return [Boolean]
+      #
       def finished?
-        blocked? || response || error
+        blocked? || !response.nil? || !error.nil?
       end
 
+      #
+      # Determines if the network exchange is still not finished.
+      #
+      # @return [Boolean]
+      #
       def pending?
         !finished?
       end
 
+      #
+      # Determines if the exchange's request was intercepted.
+      #
+      # @return [Boolean]
+      #
       def intercepted?
-        intercepted_request
+        !intercepted_request.nil?
+      end
+
+      #
+      # Returns request's URL.
+      #
+      # @return [String, nil]
+      #
+      def url
+        request&.url
       end
 
+      #
+      # Converts the network exchange into a request, response, and error tuple.
+      #
+      # @return [Array]
+      #
       def to_a
         [request, response, error]
       end
 
+      #
+      # Inspects the network exchange.
+      #
+      # @return [String]
+      #
       def inspect
         "#<#{self.class} " \
           "@id=#{@id.inspect} " \

data/lib/ferrum/network/request.rb

@@ -4,48 +4,112 @@ require "time"
 
 module Ferrum
   class Network
+    #
+    # Represents a [Network.Request](https://chromedevtools.github.io/devtools-protocol/1-3/Network/#type-Request)
+    # object.
+    #
     class Request
+      #
+      # Initializes the request object.
+      #
+      # @param [Hash{String => Object}] params
+      #   The parsed JSON attributes.
+      #
       def initialize(params)
         @params = params
         @request = @params["request"]
       end
 
+      #
+      # The request ID.
+      #
+      # @return [String]
+      #
       def id
         @params["requestId"]
       end
 
+      #
+      # The request resouce type.
+      #
+      # @return [String]
+      #
       def type
         @params["type"]
       end
 
+      #
+      # Determines if the request is of the given type.
+      #
+      # @param [String, Symbol] value
+      #   The type value to compare against.
+      #
+      # @return [Boolean]
+      #
       def type?(value)
         type.downcase == value.to_s.downcase
       end
 
+      #
+      # The frame ID of the request.
+      #
+      # @return [String]
+      #
       def frame_id
         @params["frameId"]
       end
 
+      #
+      # 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 request timestamp.
+      #
+      # @return [Time]
+      #
       def time
         @time ||= Time.strptime(@params["wallTime"].to_s, "%s")
       end
 
+      #
+      # The optional HTTP `POST` form data.
+      #
+      # @return [String, nil]
+      #   The HTTP `POST` form data.
+      #
       def post_data
         @request["postData"]
       end

data/lib/ferrum/network/response.rb

@@ -2,43 +2,105 @@
 
 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
+
+      #
+      # Initializes the respones 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,6 +114,11 @@ module Ferrum
         @body_size = size - headers_size
       end
 
+      #
+      # The response body.
+      #
+      # @return [String]
+      #
       def body
         @body ||= begin
           body, encoded = @page
@@ -61,14 +128,29 @@ module Ferrum
         end
       end
 
+      #
+      # @return [Boolean]
+      #
       def main?
         @page.network.response == self
       end
 
+      #
+      # Comapres the respones 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

data/lib/ferrum/network.rb

@@ -19,6 +19,16 @@ module Ferrum
     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 +39,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 +84,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,6 +163,30 @@ module Ferrum
     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 }
       pattern[:resourceType] = resource_type if resource_type && RESOURCE_TYPES.include?(resource_type.to_s)
@@ -98,6 +194,31 @@ module Ferrum
       @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)
       raise ArgumentError, AUTHORIZE_TYPE_WRONG unless AUTHORIZE_TYPE.include?(type)
       raise ArgumentError, AUTHORIZE_BLOCK_MISSING if !block_given? && !@page.subscribed?("Fetch.requestPaused")
@@ -151,6 +272,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,6 +318,14 @@ module Ferrum
       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