Class: Ferrum::Browser

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/ferrum/browser.rb,
lib/ferrum/browser/xvfb.rb,
lib/ferrum/browser/binary.rb,
lib/ferrum/browser/command.rb,
lib/ferrum/browser/options.rb,
lib/ferrum/browser/process.rb,
lib/ferrum/browser/options/base.rb,
lib/ferrum/browser/version_info.rb,
lib/ferrum/browser/options/chrome.rb,
lib/ferrum/browser/options/firefox.rb

Defined Under Namespace

Modules: Binary Classes: Command, Options, Process, VersionInfo, Xvfb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = nil) ⇒ Browser

Initializes the browser.

Parameters:

  • options (Hash{Symbol => Object}, nil) (defaults to: nil) —

    Additional browser options.

Options Hash (options):

  • :headless (Boolean) — default: true —

    Set browser as headless or not.

  • :xvfb (Boolean) — default: false —

    Run browser in a virtual framebuffer.

  • :flatten (Boolean) — default: true —

    Use one websocket connection to the browser and all the pages in flatten mode.

  • :window_size ((Integer, Integer)) — default: [1024, 768] —

    The dimensions of the browser window in which to test, expressed as a 2-element array, e.g. ‘[1024, 768]`.

  • :extensions (Array<String, Hash>) —

    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’” }]‘

  • :logger (#puts) —

    When present, debug output is written to this object.

  • :slowmo (Integer, Float) —

    Set a delay in seconds to wait before sending command. Useful companion of headless option, so that you have time to see changes.

  • :timeout (Numeric) — default: 5 —

    The number of seconds we’ll wait for a response when communicating with browser.

  • :js_errors (Boolean) —

    When true, JavaScript errors get re-raised in Ruby.

  • :pending_connection_errors (Boolean) — default: 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.

  • :browser_name (:chrome, :firefox) — default: :chrome —

    Sets the browser’s name. Note: only experimental support for ‘:firefox` for now.

  • :browser_path (String) —

    Path to Chrome binary, you can also set ENV variable as ‘BROWSER_PATH=some/path/chrome bundle exec rspec`.

  • :browser_options (Hash) —

    Additional command line options, [see them all](peter.sh/experiments/chromium-command-line-switches/) e.g. ‘{ “ignore-certificate-errors” => nil }`

  • :ignore_default_browser_options (Boolean) —

    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.

  • :port (Integer) —

    Remote debugging port for headless Chrome.

  • :host (String) —

    Remote debugging address for headless Chrome.

  • :url (String) —

    URL for a running instance of Chrome. If this is set, a browser process will not be spawned.

  • :process_timeout (Integer) —

    How long to wait for the Chrome process to respond on startup.

  • :ws_max_receive_size (Integer) —

    How big messages to accept from Chrome over the web socket, in bytes. Defaults to 64MB. Incoming messages larger this will cause a DeadBrowserError.

  • :proxy (Hash) —

    Specify proxy settings, [read more](github.com/rubycdp/ferrum#proxy).

  • :save_path (String) —

    Path to save attachments with [Content-Disposition](developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header.

  • :env (Hash) —

    Environment variables you’d like to pass through to the process.



128
129
130
131
132
133
 
# File 'lib/ferrum/browser.rb', line 128

def initialize(options = nil)
  @options = Options.new(options)
  @client = @process = @contexts = nil

  start
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



33
34
35
 
# File 'lib/ferrum/browser.rb', line 33

def client
  @client
end

#contexts ⇒ Object (readonly)

Returns the value of attribute contexts.



33
34
35
 
# File 'lib/ferrum/browser.rb', line 33

def contexts
  @contexts
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



33
34
35
 
# File 'lib/ferrum/browser.rb', line 33

def options
  @options
end

#process ⇒ Object (readonly)

Returns the value of attribute process.



33
34
35
 
# File 'lib/ferrum/browser.rb', line 33

def process
  @process
end

Instance Method Details

#crash ⇒ Object 



221
222
223
 
# File 'lib/ferrum/browser.rb', line 221

def crash
  command("Browser.crash")
end

#create_page(new_context: false, proxy: nil) ⇒ Ferrum::Page

Creates a new page.

Parameters:

  • new_context (Boolean) (defaults to: false) —

    Whether to create a page in a new context or not.

  • proxy (Hash) (defaults to: nil) —

    Whether to use proxy for a page. The page will be created in a new context if so.

Returns:



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/ferrum/browser.rb', line 147

def create_page(new_context: false, proxy: nil)
  page = if new_context || proxy
           params = {}

           if proxy
             options.validate_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

  block_given? ? yield(page) : page
ensure
  if block_given?
    page&.close
    context.dispose if new_context
  end
end

#evaluate_on_new_document(expression) ⇒ Object

Evaluate JavaScript to modify things before a page load.

Examples:

browser.evaluate_on_new_document <<~JS
  Object.defineProperty(navigator, "languages", {
    get: function() { return ["tlh"]; }
  });
JS

Parameters:

  • expression (String) —

    The JavaScript to add to each new document.



184
185
186
 
# File 'lib/ferrum/browser.rb', line 184

def evaluate_on_new_document(expression)
  extensions << expression
end

#headless_new? ⇒ Boolean

Returns:

  • (Boolean) 


236
237
238
 
# File 'lib/ferrum/browser.rb', line 236

def headless_new?
  process&.command&.headless_new?
end

#quit ⇒ Object 



211
212
213
214
215
216
217
218
219
 
# File 'lib/ferrum/browser.rb', line 211

def quit
  return unless @client

  contexts.close_connections

  @client.close
  @process.stop
  @client = @process = @contexts = nil
end

#reset ⇒ Object

Closes browser tabs opened by the ‘Browser` instance.

Examples:

# 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


202
203
204
 
# File 'lib/ferrum/browser.rb', line 202

def reset
  contexts.reset
end

#restart ⇒ Object 



206
207
208
209
 
# File 'lib/ferrum/browser.rb', line 206

def restart
  quit
  start
end

#version ⇒ VersionInfo

Gets the version information from the browser.

Returns:

Since:

  • 0.13



232
233
234
 
# File 'lib/ferrum/browser.rb', line 232

def version
  VersionInfo.new(command("Browser.getVersion"))
end