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.

  • :incognito (Boolean) — default: true —

    Create an incognito profile for the browser startup window.

  • :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.


132
133
134
135
136
137
 
# File 'lib/ferrum/browser.rb', line 132

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.


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

def client
  @client
end

#contexts ⇒ Object (readonly)

Returns the value of attribute contexts.


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

def contexts
  @contexts
end

#options ⇒ Object (readonly)

Returns the value of attribute options.


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

def options
  @options
end

#process ⇒ Object (readonly)

Returns the value of attribute process.


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

def process
  @process
end

Instance Method Details

#close ⇒ Object

Close browser gracefully.

You should clean up resources/connections in ruby world manually, it’s only a CDP command.


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

def close
  command("Browser.close")
end

#crash ⇒ Object

Crashes browser.


228
229
230
 
# File 'lib/ferrum/browser.rb', line 228

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:


151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/ferrum/browser.rb', line 151

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

#debug(bind = nil) ⇒ void

This method returns an undefined value.

Opens headless session in the browser devtools frontend.

Since:

  • 0.16


259
260
261
262
263
264
265
266
267
268
 
# File 'lib/ferrum/browser.rb', line 259

def debug(bind = nil)
  ::Process.spawn(process.path, debug_url)

  bind ||= binding
  if bind.respond_to?(:pry)
    Pry.start(bind)
  else
    bind.irb
  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.


188
189
190
 
# File 'lib/ferrum/browser.rb', line 188

def evaluate_on_new_document(expression)
  extensions << expression
end

#quit ⇒ Object 


215
216
217
218
219
220
221
222
223
 
# File 'lib/ferrum/browser.rb', line 215

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

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

def reset
  contexts.reset
end

#restart ⇒ Object 


210
211
212
213
 
# File 'lib/ferrum/browser.rb', line 210

def restart
  quit
  start
end

#version ⇒ VersionInfo

Gets the version information from the browser.

Returns:

Since:

  • 0.13


248
249
250
 
# File 'lib/ferrum/browser.rb', line 248

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