ferrum 0.12 → 0.14

data/lib/ferrum/browser.rb

@@ -6,16 +6,14 @@ require "ferrum/page"
 require "ferrum/proxy"
 require "ferrum/contexts"
 require "ferrum/browser/xvfb"
+require "ferrum/browser/options"
 require "ferrum/browser/process"
 require "ferrum/browser/client"
 require "ferrum/browser/binary"
+require "ferrum/browser/version_info"
 
 module Ferrum
   class Browser
-    DEFAULT_TIMEOUT = ENV.fetch("FERRUM_DEFAULT_TIMEOUT", 5).to_i
-    WINDOW_SIZE = [1024, 768].freeze
-    BASE_URL_SCHEMA = %w[http https].freeze
-
     extend Forwardable
     delegate %i[default_context] => :contexts
     delegate %i[targets create_target page pages windows] => :default_context
@@ -24,7 +22,7 @@ module Ferrum
                 body doctype content=
                 headers cookies network
                 mouse keyboard
-                screenshot pdf mhtml viewport_size
+                screenshot pdf mhtml viewport_size device_pixel_ratio
                 frames frame_by main_frame
                 evaluate evaluate_on evaluate_async execute evaluate_func
                 add_script_tag add_style_tag bypass_csp
@@ -32,66 +30,146 @@ module Ferrum
                 playback_rate playback_rate=] => :page
     delegate %i[default_user_agent] => :process
 
-    attr_reader :client, :process, :contexts, :logger, :js_errors, :pending_connection_errors,
-                :slowmo, :base_url, :options, :window_size, :ws_max_receive_size, :proxy_options,
-                :proxy_server
-    attr_writer :timeout
+    attr_reader :client, :process, :contexts, :options, :window_size, :base_url
+    attr_accessor :timeout
 
+    #
+    # Initializes the browser.
+    #
+    # @param [Hash{Symbol => Object}, nil] options
+    #   Additional browser options.
+    #
+    # @option options [Boolean] :headless (true)
+    #   Set browser as headless or not.
+    #
+    # @option options [Boolean] :xvfb (false)
+    #   Run browser in a virtual framebuffer.
+    #
+    # @option options [(Integer, Integer)] :window_size ([1024, 768])
+    #   The dimensions of the browser window in which to test, expressed as a
+    #   2-element array, e.g. `[1024, 768]`.
+    #
+    # @option options [Array<String, Hash>] :extensions
+    #   An array of paths to files or JS source code to be preloaded into the
+    #   browser e.g.: `["/path/to/script.js", { source: "window.secret = 'top'" }]`
+    #
+    # @option options [#puts] :logger
+    #   When present, debug output is written to this object.
+    #
+    # @option options [Integer, Float] :slowmo
+    #   Set a delay in seconds to wait before sending command.
+    #   Useful companion of headless option, so that you have time to see
+    #   changes.
+    #
+    # @option options [Numeric] :timeout (5)
+    #   The number of seconds we'll wait for a response when communicating with
+    #   browser.
+    #
+    # @option options [Boolean] :js_errors
+    #   When true, JavaScript errors get re-raised in Ruby.
+    #
+    # @option options [Boolean] :pending_connection_errors (true)
+    #   When main frame is still waiting for slow responses while timeout is
+    #   reached {PendingConnectionsError} is raised. It's better to figure out
+    #   why you have slow responses and fix or block them rather than turn this
+    #   setting off.
+    #
+    # @option options [:chrome, :firefox] :browser_name (:chrome)
+    #   Sets the browser's name. **Note:** only experimental support for
+    #   `:firefox` for now.
+    #
+    # @option options [String] :browser_path
+    #   Path to Chrome binary, you can also set ENV variable as
+    #   `BROWSER_PATH=some/path/chrome bundle exec rspec`.
+    #
+    # @option options [Hash] :browser_options
+    #   Additional command line options, [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
+    #   e.g. `{ "ignore-certificate-errors" => nil }`
+    #
+    # @option options [Boolean] :ignore_default_browser_options
+    #   Ferrum has a number of default options it passes to the browser,
+    #   if you set this to `true` then only options you put in
+    #   `:browser_options` will be passed to the browser, except required ones
+    #   of course.
+    #
+    # @option options [Integer] :port
+    #   Remote debugging port for headless Chrome.
+    #
+    # @option options [String] :host
+    #   Remote debugging address for headless Chrome.
+    #
+    # @option options [String] :url
+    #   URL for a running instance of Chrome. If this is set, a browser process
+    #   will not be spawned.
+    #
+    # @option options [Integer] :process_timeout
+    #   How long to wait for the Chrome process to respond on startup.
+    #
+    # @option options [Integer] :ws_max_receive_size
+    #   How big messages to accept from Chrome over the web socket, in bytes.
+    #   Defaults to 64MB. Incoming messages larger this will cause a
+    #   {Ferrum::DeadBrowserError}.
+    #
+    # @option options [Hash] :proxy
+    #   Specify proxy settings, [read more](https://github.com/rubycdp/ferrum#proxy).
+    #
+    # @option options [String] :save_path
+    #   Path to save attachments with [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)
+    #   header.
+    #
+    # @option options [Hash] :env
+    #   Environment variables you'd like to pass through to the process.
+    #
     def initialize(options = nil)
-      options ||= {}
-
-      @client = nil
-      @window_size = options.fetch(:window_size, WINDOW_SIZE)
-      @original_window_size = @window_size
-
-      @options = Hash(options.merge(window_size: @window_size))
-      @logger, @timeout, @ws_max_receive_size =
-        @options.values_at(:logger, :timeout, :ws_max_receive_size)
-      @js_errors = @options.fetch(:js_errors, false)
-
-      if @options[:proxy]
-        @proxy_options = @options[:proxy]
-
-        if @proxy_options[:server]
-          @proxy_server = Proxy.start(**@proxy_options.slice(:host, :port, :user, :password))
-          @proxy_options.merge!(host: @proxy_server.host, port: @proxy_server.port)
-        end
-
-        @options[:browser_options] ||= {}
-        address = "#{@proxy_options[:host]}:#{@proxy_options[:port]}"
-        @options[:browser_options].merge!("proxy-server" => address)
-        @options[:browser_options].merge!("proxy-bypass-list" => @proxy_options[:bypass]) if @proxy_options[:bypass]
-      end
-
-      @pending_connection_errors = @options.fetch(:pending_connection_errors, true)
-      @slowmo = @options[:slowmo].to_f
-
-      self.base_url = @options[:base_url] if @options.key?(:base_url)
-
-      if ENV.fetch("FERRUM_DEBUG", nil) && !@logger
-        $stdout.sync = true
-        @logger = $stdout
-        @options[:logger] = @logger
-      end
+      @options = Options.new(options)
+      @client = @process = @contexts = nil
 
-      @options.freeze
+      @timeout = @options.timeout
+      @window_size = @options.window_size
+      @base_url = @options.base_url if @options.base_url
 
       start
     end
 
+    #
+    # Sets the base URL.
+    #
+    # @param [String] value
+    #   The new base URL value.
+    #
+    # @raise [ArgumentError] when path is not absolute or doesn't include schema
+    #
+    # @return [Addressable::URI]
+    #   The parsed base URI value.
+    #
     def base_url=(value)
-      parsed = Addressable::URI.parse(value)
-      unless BASE_URL_SCHEMA.include?(parsed.normalized_scheme)
-        raise "Set `base_url` should be absolute and include schema: #{BASE_URL_SCHEMA}"
-      end
-
-      @base_url = parsed
+      @base_url = options.parse_base_url(value)
     end
 
-    def create_page(new_context: false)
-      page = if new_context
-               context = contexts.create
-               context.create_page
+    #
+    # Creates a new page.
+    #
+    # @param [Boolean] new_context
+    #   Whether to create a page in a new context or not.
+    #
+    # @param [Hash] proxy
+    #   Whether to use proxy for a page. The page will be created in a new context if so.
+    #
+    # @return [Ferrum::Page]
+    #   Created page.
+    #
+    def create_page(new_context: false, proxy: nil)
+      page = if new_context || proxy
+               params = {}
+
+               if proxy
+                 options.parse_proxy(proxy)
+                 params.merge!(proxyServer: "#{proxy[:host]}:#{proxy[:port]}")
+                 params.merge!(proxyBypassList: proxy[:bypass]) if proxy[:bypass]
+               end
+
+               context = contexts.create(**params)
+               context.create_page(proxy: proxy)
              else
                default_context.create_page
              end
@@ -99,25 +177,34 @@ module Ferrum
       block_given? ? yield(page) : page
     ensure
       if block_given?
-        page.close
+        page&.close
         context.dispose if new_context
       end
     end
 
     def extensions
-      @extensions ||= Array(@options[:extensions]).map do |ext|
+      @extensions ||= Array(options.extensions).map do |ext|
         (ext.is_a?(Hash) && ext[:source]) || File.read(ext)
       end
     end
 
+    #
+    # Evaluate JavaScript to modify things before a page load.
+    #
+    # @param [String] expression
+    #   The JavaScript to add to each new document.
+    #
+    # @example
+    #   browser.evaluate_on_new_document <<~JS
+    #     Object.defineProperty(navigator, "languages", {
+    #       get: function() { return ["tlh"]; }
+    #     });
+    #   JS
+    #
     def evaluate_on_new_document(expression)
       extensions << expression
     end
 
-    def timeout
-      @timeout || DEFAULT_TIMEOUT
-    end
-
     def command(*args)
       @client.command(*args)
     rescue DeadBrowserError
@@ -125,8 +212,22 @@ module Ferrum
       raise
     end
 
+    #
+    # Closes browser tabs opened by the `Browser` instance.
+    #
+    # @example
+    #   # connect to a long-running Chrome process
+    #   browser = Ferrum::Browser.new(url: 'http://localhost:9222')
+    #
+    #   browser.go_to("https://github.com/")
+    #
+    #   # clean up, lest the tab stays there hanging forever
+    #   browser.reset
+    #
+    #   browser.quit
+    #
     def reset
-      @window_size = @original_window_size
+      @window_size = options.window_size
       contexts.reset
     end
 
@@ -136,6 +237,8 @@ module Ferrum
     end
 
     def quit
+      return unless @client
+
       @client.close
       @process.stop
       @client = @process = @contexts = nil
@@ -150,12 +253,29 @@ module Ferrum
       command("Browser.crash")
     end
 
+    #
+    # Gets the version information from the browser.
+    #
+    # @return [VersionInfo]
+    #
+    # @since 0.13
+    #
+    def version
+      VersionInfo.new(command("Browser.getVersion"))
+    end
+
+    def headless_new?
+      process&.command&.headless_new?
+    end
+
     private
 
     def start
       Utils::ElapsedTime.start
-      @process = Process.start(@options)
-      @client = Client.new(self, @process.ws_url)
+      @process = Process.start(options)
+      @client = Client.new(@process.ws_url, self,
+                           logger: options.logger,
+                           ws_max_receive_size: options.ws_max_receive_size)
       @contexts = Contexts.new(self)
     end
   end

data/lib/ferrum/context.rb

@@ -40,8 +40,9 @@ module Ferrum
       windows.map(&:page)
     end
 
-    def create_page
-      create_target.page
+    def create_page(**options)
+      target = create_target
+      target.page = target.build_page(**options)
     end
 
     def create_target

data/lib/ferrum/contexts.rb

@@ -23,8 +23,8 @@ module Ferrum
       context
     end
 
-    def create
-      response = @browser.command("Target.createBrowserContext")
+    def create(**options)
+      response = @browser.command("Target.createBrowserContext", **options)
       context_id = response["browserContextId"]
       context = Context.new(@browser, self, context_id)
       @contexts[context_id] = context

data/lib/ferrum/cookies/cookie.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Ferrum
+  class Cookies
+    #
+    # Represents a [cookie value](https://chromedevtools.github.io/devtools-protocol/1-3/Network/#type-Cookie).
+    #
+    class Cookie
+      # The parsed JSON attributes.
+      #
+      # @return [Hash{String => [String, Boolean, nil]}]
+      attr_reader :attributes
+
+      #
+      # Initializes the cookie.
+      #
+      # @param [Hash{String => String}] attributes
+      #   The parsed JSON attributes.
+      #
+      def initialize(attributes)
+        @attributes = attributes
+      end
+
+      #
+      # The cookie's name.
+      #
+      # @return [String]
+      #
+      def name
+        attributes["name"]
+      end
+
+      #
+      # The cookie's value.
+      #
+      # @return [String]
+      #
+      def value
+        attributes["value"]
+      end
+
+      #
+      # The cookie's domain.
+      #
+      # @return [String]
+      #
+      def domain
+        attributes["domain"]
+      end
+
+      #
+      # The cookie's path.
+      #
+      # @return [String]
+      #
+      def path
+        attributes["path"]
+      end
+
+      #
+      # The `sameSite` configuration.
+      #
+      # @return ["Strict", "Lax", "None", nil]
+      #
+      def samesite
+        attributes["sameSite"]
+      end
+      alias same_site samesite
+
+      #
+      # The cookie's size.
+      #
+      # @return [Integer]
+      #
+      def size
+        attributes["size"]
+      end
+
+      #
+      # Specifies whether the cookie is secure or not.
+      #
+      # @return [Boolean]
+      #
+      def secure?
+        attributes["secure"]
+      end
+
+      #
+      # Specifies whether the cookie is HTTP-only or not.
+      #
+      # @return [Boolean]
+      #
+      def httponly?
+        attributes["httpOnly"]
+      end
+      alias http_only? httponly?
+
+      #
+      # Specifies whether the cookie is a session cookie or not.
+      #
+      # @return [Boolean]
+      #
+      def session?
+        attributes["session"]
+      end
+
+      #
+      # Specifies when the cookie will expire.
+      #
+      # @return [Time, nil]
+      #
+      def expires
+        Time.at(attributes["expires"]) if attributes["expires"].positive?
+      end
+
+      #
+      # The priority of the cookie.
+      #
+      # @return [String]
+      #
+      def priority
+        @attributes["priority"]
+      end
+
+      #
+      # @return [Boolean]
+      #
+      def sameparty?
+        @attributes["sameParty"]
+      end
+
+      alias same_party? sameparty?
+
+      #
+      # @return [String]
+      #
+      def source_scheme
+        @attributes["sourceScheme"]
+      end
+
+      #
+      # @return [Integer]
+      #
+      def source_port
+        @attributes["sourcePort"]
+      end
+
+      #
+      # Compares different cookie objects.
+      #
+      # @return [Boolean]
+      #
+      def ==(other)
+        other.class == self.class && other.attributes == attributes
+      end
+
+      #
+      # Converts the cookie back into a raw cookie String.
+      #
+      # @return [String]
+      #   The raw cookie string.
+      #
+      def to_s
+        string = String.new("#{@attributes['name']}=#{@attributes['value']}")
+
+        @attributes.each do |key, value|
+          case key
+          when "name", "value" # no-op
+          when "domain"   then string << "; Domain=#{value}"
+          when "path"     then string << "; Path=#{value}"
+          when "expires"  then string << "; Expires=#{Time.at(value).httpdate}"
+          when "httpOnly" then string << "; httpOnly" if value
+          when "secure"   then string << "; Secure"   if value
+          end
+        end
+
+        string
+      end
+
+      alias to_h attributes
+    end
+  end
+end