Ferrum Documentation

Ferrum is fully thread-safe. To manage multiple independent sessions within a single browser instance, use browser.contexts.create.

A Context acts like an incognito profile. You can create multiple pages within one context to share session data, or create multiple contexts to ensure complete isolation between threads. Always remember to call context.dispose to clean up the context resources.

browser = Ferrum::Browser.new
context = browser.contexts.create

t1 = Thread.new(context) do |c|
  page = c.create_page
  page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
  page.screenshot(path: "t1.png")
end

t2 = Thread.new(context) do |c|
  page = c.create_page
  page.go_to("https://www.google.com/search?q=Ruby+static+typing")
  page.screenshot(path: "t2.png")
end

t1.join
t2.join

context.dispose
browser.quit

To use Ferrum, add it to your Gemfile and run bundle install.

Prerequisites:

• Ruby
• Chrome or Chromium.

Ensure the Chrome binary is in your PATH or BROWSER_PATH. You can also specify the path manually using the :browser_path option during initialization.

gem "ferrum"

To interact with browser dialogs (like alerts, confirms, or prompts), register an event listener on the page object using page.on(:dialog). The listener receives a dialog object, which you can inspect and act upon.

Common workflow:

1. Use dialog.match?(regex) to check the dialog's text.
2. Use dialog.accept(text) to accept the dialog. If it is a prompt, pass the desired response string as the text argument. If it is a standard alert, call accept without arguments.
3. Use dialog.dismiss to close the dialog without interacting with it.

page.on(:dialog) do |dialog|
  if dialog.match?(/bla-bla/)
    dialog.accept
  else
    dialog.dismiss
  end
end
page.go_to("https://google.com")

When running Ferrum inside a Docker container as the root user, you must enable the dockerize: true option to pass the necessary CLI flags to the browser.

For CI environments, you can set the FERRUM_CHROME_DOCKERIZE=true environment variable to automatically apply this setting to all browser instances.

Ferrum::Browser.new(dockerize: true)

The bin/console script provides an interactive IRB (Interactive Ruby) session pre-loaded with the ferrum library. This allows you to manipulate a Chrome browser instance manually through a Ruby REPL.

To start a session, run the script from your terminal. Once inside the IRB session, you can use the helper method browser to initialize a Ferrum::Browser instance. By default, browser starts in headless: true mode, but you can pass options to change this.

When debugging, you can increase the communication timeout and use slowmo to add a delay (in seconds) before every command, making it easier to follow the browser's actions.

# Set custom timeout and slowmo for debugging
Ferrum::Browser.new(timeout: 10, slowmo: 0.5)

To see the browser actions visually, set headless: false. You can also specify the window dimensions using the window_size array.

# Run in headful mode with custom window size
Ferrum::Browser.new(headless: false, window_size: [1920, 1080])

To interact with web forms or use shortcuts, focus the target element and use page.keyboard.

Type text into an input

page.go_to("https://google.com")
input = page.at_css("input[name='q']")
input.focus
page.keyboard.type("Hello World")

Press Enter

page.keyboard.type(:Enter)

Use keyboard shortcuts (e.g., Shift + text)

page.keyboard.down(:Shift)
page.keyboard.type("h", "e", "l", "l", "o")
page.keyboard.up(:Shift)

If Chrome is not in your default path, specify the location using browser_path. Alternatively, you can set the BROWSER_PATH environment variable.

# Use custom Chrome binary
Ferrum::Browser.new(browser_path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")

Ferrum provides a mouse API to simulate user interactions like moving the cursor, clicking, and dragging. Methods are chainable.

# Trace a 100x100 square
browser = Ferrum::Browser.new
page = browser.create_page
page.go_to("https://google.com")
browser.mouse
  .move(x: 0, y: 0)
  .down
  .move(x: 0, y: 100)
  .move(x: 100, y: 100)
  .move(x: 100, y: 0)
  .move(x: 0, y: 0)
  .up

browser.quit