### Install Ferrum Gem

Source: https://github.com/rubycdp/ferrum/blob/main/README.md

Add the Ferrum gem to your Gemfile to include it in your project. Run `bundle install` afterwards.

```ruby
gem "ferrum"
```

--------------------------------

### Get All Headers

Source: https://github.com/rubycdp/ferrum/blob/main/docs/12-headers.md

Retrieves all currently set headers.

```APIDOC
## GET page.headers

### Description
Get all headers.

### Method
GET

### Endpoint
page.headers
```

--------------------------------

### Start Screencast and Save Frames

Source: https://github.com/rubycdp/ferrum/blob/main/docs/6-screencast.md

Starts sending frames to record screencast. Frames are Base64 encoded images that are decoded and saved to files. Chrome only sends new frames when page content changes.

```ruby
require "base64"

page.go_to("https://apple.com/ipad")

page.start_screencast(format: :jpeg, quality: 75) do |data, metadata|
  timestamp = (metadata["timestamp"] * 1000).to_i
  File.binwrite("image_#{timestamp}.jpg", Base64.decode64(data))
end

sleep 10

page.stop_screencast
```

--------------------------------

### Example: Interacting with Elements within a Frame

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Demonstrates how to access a frame and then use finders to locate elements specifically within that frame's context.

```APIDOC
## Example: Interacting with Elements within a Frame

### Description
You can access a frame and then use finders to locate elements within that frame.

### Request Example
```ruby
page.go_to("https://example.com/page-with-iframe")
frame = page.at_xpath("//iframe").frame # => Frame
frame.at_css("//a[text() = 'Log in']") # => Node
```
```

--------------------------------

### start_screencast

Source: https://github.com/rubycdp/ferrum/blob/main/docs/6-screencast.md

Starts sending frames to record screencast to the given block. The block receives base64-encoded image data, metadata, and the session ID for each frame.

```APIDOC
## start_screencast

### Description
Starts sending frames to record screencast to the given block.

### Method
`start_screencast`

### Parameters
#### Options
- **:format** (Symbol) - Optional - `:jpeg` | `:png` The format the image should be returned in.
- **:quality** (Integer) - Optional - The image quality. Note: 0-100 works for JPEG only.
- **:max_width** (Integer) - Optional - Maximum screencast frame width.
- **:max_height** (Integer) - Optional - Maximum screencast frame height.
- **:every_nth_frame** (Integer) - Optional - Send every n-th frame.

#### Block Inputs
- **data** (String) - Base64-encoded compressed image.
- **metadata** (Hash) - Screencast frame metadata.
  - **"offsetTop"** (Integer) - Top offset in DIP.
  - **"pageScaleFactor"** (Integer) - Page scale factor.
  - **"deviceWidth"** (Integer) - Device screen width in DIP.
  - **"deviceHeight"** (Integer) - Device screen height in DIP.
  - **"scrollOffsetX"** (Integer) - Position of horizontal scroll in CSS pixels.
  - **"scrollOffsetY"** (Integer) - Position of vertical scroll in CSS pixels.
  - **"timestamp"** (Float) - Optional - Frame swap timestamp in seconds since Unix epoch.
- **session_id** (Integer) - Frame number.

### Request Example
```ruby
page.start_screencast(format: :jpeg, quality: 75) do |data, metadata|
  timestamp = (metadata["timestamp"] * 1000).to_i
  File.binwrite("image_#{timestamp}.jpg", Base64.decode64(data))
end
```

### Response
No explicit response defined, but the block receives frame data.
```

--------------------------------

### Evaluate JavaScript for Page Dimensions

Source: https://github.com/rubycdp/ferrum/blob/main/README.md

Use the `evaluate` method to execute JavaScript within the page context and retrieve results. This example gets the full width and height of the document.

```ruby
browser = Ferrum::Browser.new
page = browser.create_page
page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
width, height = page.evaluate <<~JS
  [document.documentElement.offsetWidth,
   document.documentElement.offsetHeight]
JS
# => [1024, 1931]
browser.quit
```

--------------------------------

### Get Downloaded Files Information - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/8-downloads.md

Retrieves information about all downloaded files. This is useful for verifying download status and details.

```ruby
page.go_to("http://localhost/attachment.pdf")
page.downloads.files # => [{"frameId"=>"E3316DF1B5383D38F8ADF7485005FDE3", "guid"=>"11a68745-98ac-4d54-9b57-9f9016c268b3", "url"=>"http://localhost/attachment.pdf", "suggestedFilename"=>"attachment.pdf", "totalBytes"=>4911, "receivedBytes"=>4911, "state"=>"completed"}]
```

--------------------------------

### position

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Gets the current position of the browser window on the screen.

```APIDOC
## position

### Description
Gets the current position of the browser window.

### Response
#### Success Response (200)
- **position** (Array<Integer>) - An array containing the [left, top] coordinates of the window.
```

--------------------------------

### Perform Mouse Movements

Source: https://github.com/rubycdp/ferrum/blob/main/README.md

Utilize the `mouse` API to simulate mouse actions like moving, clicking (down/up), and tracing paths. This example traces a square.

```ruby
# Trace a 100x100 square
browser = Ferrum::Browser.new
page = browser.create_page
page.go_to("https://google.com")
page.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
```

--------------------------------

### Get Window Bounds - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Retrieve the current window bounds as a hash, including `left`, `top`, `width`, `height`, and `windowState`.

```ruby
browser.window_bounds # => { "left": 0, "top": 1286, "width": 10, "height": 10, "windowState": "normal" }
```

--------------------------------

### Simulate Mouse Movements

Source: https://github.com/rubycdp/ferrum/blob/main/docs/1-introduction.md

Use the `mouse` API to perform complex mouse interactions, such as tracing a square by moving the mouse, pressing/releasing the button, and returning to the start.

```ruby
# Trace a 100x100 square
browser = Ferrum::Browser.new
page = browser.create_page
page.go_to("https://google.com")
page.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
```

--------------------------------

### Main Frame Response

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Gets the response object for the main frame of the page.

```APIDOC
## Main Frame Response

### Description
Provides the response object for the main frame of the current page.

### Method
`page.network.response`

### Response
#### Success Response
- `Network::Response`: The response object for the main frame.

### Request Example
```ruby
page.go_to("https://github.com/")
page.network.response # => #<Ferrum::Network::Response...>
```
```

--------------------------------

### Get Frame Title

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves the title of a specific frame. This can be helpful for identifying the content of a frame.

```ruby
page.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = page.frames[1]
frame.title # => HTML Demo: <iframe>
```

--------------------------------

### Main Frame Request

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Gets the request object for the main frame of the page.

```APIDOC
## Main Frame Request

### Description
Provides the request object for the main frame of the current page.

### Method
`page.network.request`

### Response
#### Success Response
- `Network::Request`: The request object for the main frame.

### Request Example
```ruby
page.go_to("https://github.com/")
page.network.request # => #<Ferrum::Network::Request...>
```
```

--------------------------------

### Get All Cookies

Source: https://github.com/rubycdp/ferrum/blob/main/docs/11-cookies.md

Retrieves all cookies for the current page as a hash. Useful for inspecting all available cookies.

```ruby
page.cookies.all
```

--------------------------------

### window_bounds

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Gets the current bounds (position, dimensions, and state) of the browser window.

```APIDOC
## window_bounds

### Description
Gets the current bounds for the browser window.

### Response
#### Success Response (200)
- **window_bounds** (Hash<String, Integer | String>) - A hash containing the window's properties: `left`, `top`, `width`, `height`, and `windowState`.
```

--------------------------------

### Accessing Main Frame

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Get the main frame of the page, which is the top-level document and the parent of all other frames.

```APIDOC
## main_frame

### Description
Returns the page's main frame, which is the top of the frame tree and the parent of all other frames.

### Method
`page.main_frame`

### Response
#### Success Response (Frame)
Returns the main Frame object.

### Request Example
```ruby
page.main_frame
```
```

--------------------------------

### Get Main Frame Response

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Retrieves the response object for the main frame of the current page. Ensure navigation to a page has occurred.

```ruby
page.go_to("https://github.com/")
page.network.response # => #<Ferrum::Network::Response...>
```

--------------------------------

### Get Current URL

Source: https://github.com/rubycdp/ferrum/blob/main/docs/4-finders.md

The `current_url` method returns the href of the current top window location.

```ruby
page.go_to("https://google.com/")
page.current_url # => "https://www.google.com/"
```

--------------------------------

### Get Frame URL

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves the current URL of a specific frame. This is useful for verifying navigation within a frame.

```ruby
page.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = page.frames[1]
frame.url # => https://interactive-examples.mdn.mozilla.net/pages/tabbed/iframe.html
```

--------------------------------

### Get Main Frame Request

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Accesses the request object for the main frame of the current page. Navigate to a page before calling.

```ruby
page.go_to("https://github.com/")
page.network.request # => #<Ferrum::Network::Request...>
```

--------------------------------

### Get Frame Doctype

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves the doctype declaration of the main frame. This helps in understanding the document type being rendered.

```ruby
page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
page.main_frame.doctype # => "<!DOCTYPE html>"
```

--------------------------------

### Get Main Page Response Status

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Returns the HTTP status code of the main page response. This is a shortcut for `response.status`.

```ruby
page.go_to("https://github.com/")
page.network.status # => 200
```

--------------------------------

### Get Browser Window Position - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Retrieve the browser window's current position as an array of two integers: `[left, top]`.

```ruby
browser.position # => [10, 20]
```

--------------------------------

### Get All Network Traffic

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Retrieves all network traffic information as an array of Network::Exchange objects. Requires navigating to a page first.

```ruby
page.go_to("https://github.com/")
page.network.traffic # => [#<Ferrum::Network::Exchange, ...]
```

--------------------------------

### Get Current Frame URL

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves the URL of the frame's top window. This is equivalent to `frame.url` for frames that are not nested.

```ruby
page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
frame = page.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
frame.current_url # => "https://www.w3schools.com/tags/tag_frame.asp"
```

--------------------------------

### Get Frame from Node

Source: https://github.com/rubycdp/ferrum/blob/main/docs/18-node.md

Access the parent Frame object of a given Node. This allows for further DOM traversal or interaction starting from the frame context.

```ruby
frame =  page.at_xpath("//iframe").frame # => Frame
frame.at_css("//a[text() = 'Log in']") # => Node
```

--------------------------------

### Basic Navigation and Screenshot

Source: https://github.com/rubycdp/ferrum/blob/main/README.md

Instantiate a browser, navigate to a URL, and save a screenshot. Ensure the browser instance is quit when done.

```ruby
browser = Ferrum::Browser.new
browser.go_to("https://google.com")
browser.screenshot(path: "google.png")
browser.quit
```

--------------------------------

### go_to(url)

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Navigates the browser to a specified URL. The URL should include the scheme (e.g., 'http://', 'https://') unless a base URL is configured.

```APIDOC
## go_to(url)

### Description
Navigates the browser to a specified URL.

### Parameters
#### Path Parameters
- **url** (String) - Required - The URL to navigate to. Should include the scheme unless `base_url` is configured.
```

--------------------------------

### Initialize Ferrum Browser with Custom Options

Source: https://github.com/rubycdp/ferrum/blob/main/docs/2-customization.md

Customize browser behavior by passing an options hash during initialization. Options include headless mode, window size, and debugging settings.

```ruby
Ferrum::Browser.new(options)
```

--------------------------------

### window_id

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Gets the unique identifier for the current browser window.

```APIDOC
## window_id

### Description
Gets the current window ID.

### Response
#### Success Response (200)
- **window_id** (Integer) - The unique identifier for the current browser window.
```

--------------------------------

### Navigate to URL - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Use `go_to` to navigate the current page to a specified URL. The URL should include the scheme unless a `base_url` is configured.

```ruby
page.go_to("https://github.com/")
```

--------------------------------

### Connect to an Existing Chrome Instance

Source: https://github.com/rubycdp/ferrum/blob/main/docs/2-customization.md

Connect to a Chrome instance that is already running by specifying its URL.

```ruby
Ferrum::Browser.new(url: "http://localhost:9222")
```

--------------------------------

### Add Custom Browser Command Line Options

Source: https://github.com/rubycdp/ferrum/blob/main/docs/2-customization.md

Pass additional command line options to the browser instance, such as disabling web security.

```ruby
Ferrum::Browser.new(browser_options: { "disable-web-security" => nil })
```

--------------------------------

### Initialize Ferrum Browser in Docker

Source: https://github.com/rubycdp/ferrum/blob/main/docs/1-introduction.md

When running in a Docker container as root, initialize the Ferrum browser with `dockerize: true`. Alternatively, set the `FERRUM_CHROME_DOCKERIZE=true` environment variable.

```ruby
Ferrum::Browser.new(dockerize: true)
```

--------------------------------

### Use Custom Chrome Binary Path

Source: https://github.com/rubycdp/ferrum/blob/main/docs/2-customization.md

Specify a custom path to the Chrome binary if it's not in the default location or if you need to use a specific version.

```ruby
Ferrum::Browser.new(browser_path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
```

--------------------------------

### Create and Interact with a Page

Source: https://github.com/rubycdp/ferrum/blob/main/README.md

Manually create a page instance for more control. Interact with elements using selectors, focus, and type actions. The `at_css` method retrieves text content.

```ruby
browser = Ferrum::Browser.new
page = browser.create_page
page.go_to("https://google.com")
input = page.at_xpath("//input[@name='q']")
input.focus.type("Ruby headless driver for Chrome", :Enter)
page.at_css("a > h3").text # => "rubycdp/ferrum: Ruby Chrome/Chromium driver - GitHub"
browser.quit
```

--------------------------------

### Get Current Window ID - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Retrieve the unique identifier for the current browser window.

```ruby
browser.window_id # => 1
```

--------------------------------

### Set Window Bounds - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Configure the browser window's dimensions and state using `window_bounds`. Accepts `:left`, `:top`, `:width`, `:height`, and `:window_state`.

```ruby
browser.window_bounds = { left: 10, top: 20, width: 1024, height: 768, window_state: "normal" }
```

--------------------------------

### Get Current Page Title

Source: https://github.com/rubycdp/ferrum/blob/main/docs/4-finders.md

The `current_title` method returns the title of the current top window.

```ruby
page.go_to("https://google.com/")
page.current_title # => "Google"
```

--------------------------------

### Set Download Behavior - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/8-downloads.md

Configures how downloads are handled, specifying a save path and the behavior (deny, allow, allowAndName, default).

```ruby
page.go_to("https://example.com/")
page.downloads.set_behavior(save_path: "/tmp", behavior: :allow)
```

--------------------------------

### Record Trace to File

Source: https://github.com/rubycdp/ferrum/blob/main/docs/19-tracing.md

Use `tracing.record` with a block to capture a trace. Specify a `path` to save the trace data to a file. The block contains the actions to be traced.

```ruby
page.tracing.record(path: "trace.json") do
  page.go_to("https://www.google.com")
end
```

--------------------------------

### Get Page Body HTML

Source: https://github.com/rubycdp/ferrum/blob/main/docs/4-finders.md

The `body` method returns the entire HTML content of the current page.

```ruby
page.go_to("https://google.com/")
page.body # => '<html itemscope="" itemtype="http://schema.org/WebPage" lang="ru"><head>...'
```

--------------------------------

### Run in Headful Mode with Custom Window Size

Source: https://github.com/rubycdp/ferrum/blob/main/docs/2-customization.md

Configure the browser to run in headful mode and set a specific window size for testing.

```ruby
Ferrum::Browser.new(headless: false, window_size: [1920, 1080])
```

--------------------------------

### Get Specific Cookie

Source: https://github.com/rubycdp/ferrum/blob/main/docs/11-cookies.md

Retrieves a specific cookie by its name. Use this when you need to access the details of a single cookie.

```ruby
page.cookies["NID"]
```

--------------------------------

### position = (options)

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Sets the position of the browser window on the screen.

```APIDOC
## position = (options)

### Description
Sets the position for the browser window.

### Parameters
#### Request Body
- **options** (Hash) - Required - A hash containing the position coordinates.
  - **:left** (Integer) - Required - The horizontal position in pixels.
  - **:top** (Integer) - Required - The vertical position in pixels.
```

--------------------------------

### Get Current Frame Title

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves the title of the frame's top window. This is equivalent to `frame.title` for frames that are not nested.

```ruby
page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
frame = page.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
frame.current_title # => "HTML frame tag"
```

--------------------------------

### mhtml

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Saves the current page as an MHTML file on disk or returns it as a string.

```APIDOC
#### mhtml(\*\*options) : `String` | `Integer`

### Description
Saves MHTML on a disk or returns it as a string.

### Parameters
#### Options (`Hash`)
- `:path` (`String`) - to save a file on the disk.

### Request Example
```ruby
page.go_to("https://google.com/")
page.mhtml(path: "google.mhtml") # => 87742
```
```

--------------------------------

### window_bounds = (options)

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Sets the bounds (position and dimensions) of the browser window.

```APIDOC
## window_bounds = (options)

### Description
Sets the bounds for the browser window.

### Parameters
#### Request Body
- **options** (Hash) - Required - A hash containing the window bounds and state.
  - **:left** (Integer) - Required - The horizontal position in pixels.
  - **:top** (Integer) - Required - The vertical position in pixels.
  - **:width** (Integer) - Required - The width of the window in pixels.
  - **:height** (Integer) - Required - The height of the window in pixels.
  - **:window_state** (String) - Optional - The state of the window (e.g., "normal", "maximized", "minimized").
```

--------------------------------

### Save Screenshot to Disk (JPG)

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Saves a screenshot to the specified path in JPG format. Returns the size of the saved file.

```ruby
# Save on the disk in JPG
page.screenshot(path: "google.jpg") # => 30902
```

--------------------------------

### Save Screenshot to Disk (PNG)

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Saves a screenshot to the specified path in PNG format. Returns the size of the saved file.

```ruby
page.go_to("https://google.com/")
# Save on the disk in PNG
page.screenshot(path: "google.png") # => 134660
```

--------------------------------

### Get All Frames on a Page

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves an array of all `Frame` objects present on the current page. This is useful for iterating through or selecting specific frames.

```ruby
page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
page.frames # =>
# [
#   #<Ferrum::Frame @id="C6D104CE454A025FBCF22B98DE612B12" @parent_id=nil @name=nil @state=:stopped_loading @execution_id=1>,
#   #<Ferrum::Frame @id="C09C4E4404314AAEAE85928EAC109A93" @parent_id="C6D104CE454A025FBCF22B98DE612B12" @state=:stopped_loading @execution_id=2>,
#   #<Ferrum::Frame @id="2E9C7F476ED09D87A42F2FEE3C6FBC3C" @parent_id="C6D104CE454A025FBCF22B98DE612B12" @state=:stopped_loading @execution_id=3>,
#   ...
# ]
```

--------------------------------

### Thread Safety with Shared Context

Source: https://github.com/rubycdp/ferrum/blob/main/docs/1-introduction.md

Demonstrates thread safety by creating multiple pages within the same browser context. Each thread navigates to a different URL and takes a screenshot.

```ruby
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
```

--------------------------------

### wait

Source: https://github.com/rubycdp/ferrum/blob/main/docs/8-downloads.md

Waits for the download process to complete. Can optionally accept a block to perform actions before waiting.

```APIDOC
## wait(timeout = nil)

### Description
Waits until the download is finished.

### Method
`page.downloads.wait(timeout)`

### Parameters
#### Optional Parameters
- `timeout` (Integer): The maximum time in seconds to wait for the download to complete.

#### Block
An optional block can be passed to execute actions before waiting for the download to finish.

### Request Example (without block)
```ruby
page.go_to("http://localhost/attachment.pdf")
page.downloads.wait
```

### Request Example (with block)
```ruby
page.go_to("http://localhost/page")
page.downloads.wait { page.at_css("#download").click }
```
```

--------------------------------

### Handling Dialogs

Source: https://github.com/rubycdp/ferrum/blob/main/docs/16-dialogs.md

This snippet demonstrates how to intercept and respond to browser dialogs. You can accept or dismiss them based on certain conditions.

```APIDOC
## Dialogs API

### Description
Handles browser dialogs like alerts, confirms, and prompts.

### Methods
#### `accept(text)`
Accepts the dialog. Optionally provides text for prompt dialogs.

* `text` (String) - Optional text to enter into a prompt dialog.

#### `dismiss`
Dismisses the dialog.

### Example Usage
```ruby
page.on(:dialog) do |dialog|
  if dialog.match?(/bla-bla/)
    dialog.accept('User input')
  else
    dialog.dismiss
  end
end
page.go_to("https://example.com")
```
```

--------------------------------

### files

Source: https://github.com/rubycdp/ferrum/blob/main/docs/8-downloads.md

Retrieves information about all downloaded files. Returns an array of hashes, where each hash contains details about a specific download.

```APIDOC
## files

### Description
Returns all information about downloaded files as a Hash.

### Method
`page.downloads.files`

### Response
#### Success Response
- `Array<Hash>`: An array of hashes, each containing download details.
  - `frameId` (String): The ID of the frame where the download occurred.
  - `guid` (String): A unique identifier for the download.
  - `url` (String): The URL of the downloaded file.
  - `suggestedFilename` (String): The filename suggested by the server.
  - `totalBytes` (Integer): The total size of the file in bytes.
  - `receivedBytes` (Integer): The number of bytes received so far.
  - `state` (String): The current state of the download (e.g., "completed").

### Request Example
```ruby
page.go_to("http://localhost/attachment.pdf")
page.downloads.files
```

### Response Example
```json
[{"frameId":"E3316DF1B5383D38F8ADF7485005FDE3","guid":"11a68745-98ac-4d54-9b57-9f9016c268b3","url":"http://localhost/attachment.pdf","suggestedFilename":"attachment.pdf","totalBytes":4911,"receivedBytes":4911,"state":"completed"}]
```
```

--------------------------------

### Navigate Back - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Use `back` to navigate to the previous page in the browser's history. This is useful after performing actions that change the page, like clicking a link.

```ruby
page.go_to("https://github.com/")
page.at_xpath("//a").click
page.back
```

--------------------------------

### Get Frame HTML Body

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Retrieves the HTML content of the current frame's body. This is useful for inspecting or parsing the frame's content.

```ruby
page.go_to("https://www.w3schools.com/tags/tag_frame.asp")
frame = page.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
frame.body # => "<html><head></head><body></body></html>"
```

--------------------------------

### set_behavior

Source: https://github.com/rubycdp/ferrum/blob/main/docs/8-downloads.md

Configures the behavior for handling downloaded files, specifying where to save them and the download action.

```APIDOC
## set_behavior(**options)

### Description
Sets behavior in case of file to be downloaded.

### Method
`page.downloads.set_behavior(options)`

### Parameters
#### Options Hash
- `:save_path` (String) - Absolute path of where to store the file.
- `:behavior` (Symbol) - Specifies the download behavior. Possible values are `deny`, `allow`, `allowAndName`, or `default`. Defaults to `allow`.

### Request Example
```ruby
page.go_to("https://example.com/")
page.downloads.set_behavior(save_path: "/tmp", behavior: :allow)
```
```

--------------------------------

### Set Global Proxy for Ferrum Browser

Source: https://github.com/rubycdp/ferrum/blob/main/docs/9-proxy.md

Instantiate a Ferrum browser with a proxy configuration. This affects all pages and contexts opened by this browser instance.

```ruby
Ferrum::Browser.new(proxy: { host: "x.x.x.x", port: "8800", user: "user", password: "pa$$" })
```

--------------------------------

### Press Enter Key

Source: https://github.com/rubycdp/ferrum/blob/main/docs/10-mouse-keyboard.md

Simulates pressing the Enter key. This is often used after typing into a search bar or form.

```ruby
# Press Enter
page.keyboard.type(:Enter)
```

--------------------------------

### Create Page with Specific Proxy Settings

Source: https://github.com/rubycdp/ferrum/blob/main/docs/9-proxy.md

Open a new browser page within a distinct context that uses its own proxy settings. This is useful for isolating network traffic for specific pages.

```ruby
browser = Ferrum::Browser.new

browser.create_page(proxy: { host: "x.x.x.x", port: 31337, user: "user", password: "password" }) do |page|
  page.go_to("https://api.ipify.org?format=json")
  page.body # => "x.x.x.x"
end
```

```ruby
browser.create_page(proxy: { host: "y.y.y.y", port: 31337, user: "user", password: "password" }) do |page|
  page.go_to("https://api.ipify.org?format=json")
  page.body # => "y.y.y.y"
end
```

--------------------------------

### Playback Rate Control

Source: https://github.com/rubycdp/ferrum/blob/main/docs/17-animation.md

Get or set the playback rate for CSS animations. The default value is 1. A value of 2000 means the animation will play at 20 times the normal speed.

```APIDOC
## playback_rate

### Description
Returns the current playback rate for CSS animations.

### Method
GET

### Endpoint
N/A (SDK method)

### Parameters
None

### Response
#### Success Response (200)
- **playback_rate** (Integer) - The current playback rate.

### Response Example
```json
{
  "playback_rate": 1
}
```

## playback_rate = value

### Description
Sets the playback rate of CSS animations.

### Method
SET

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **value** (Integer) - Required - The desired playback rate.

### Request Example
```ruby
page.playback_rate = 2000
```

### Response
#### Success Response (200)
None (operation is a setter)

### Response Example
None
```

--------------------------------

### Save MHTML to Disk

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Saves the current page as an MHTML file to the specified path. Returns the size of the saved file.

```ruby
page.go_to("https://google.com/")
page.mhtml(path: "google.mhtml") # => 87742
```

--------------------------------

### Configure Proxy with Bypass Hosts

Source: https://github.com/rubycdp/ferrum/blob/main/docs/9-proxy.md

Specify a proxy configuration that bypasses certain hosts. Hosts matching the semi-colon-separated list will not use the proxy.

```ruby
Ferrum::Browser.new(proxy: { host: "x.x.x.x", port: "8800", bypass: "*.google.com;*foo.com" })
```

--------------------------------

### Navigate Forward - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Use `forward` to navigate to the next page in the browser's history. This is typically used after navigating back.

```ruby
page.go_to("https://github.com/")
page.at_xpath("//a").click
page.back
page.forward
```

--------------------------------

### Load Cookies from File

Source: https://github.com/rubycdp/ferrum/blob/main/docs/11-cookies.md

Loads cookies from a file (e.g., 'cookies.yml') and sets them for the current page. This is useful for restoring a previous cookie state.

```ruby
# Cookies are loaded from cookies.yml
page.cookies.load
```

--------------------------------

### Handle Dialogs with Accept/Dismiss

Source: https://github.com/rubycdp/ferrum/blob/main/docs/16-dialogs.md

Listen for dialog events and conditionally accept or dismiss them based on the dialog's text. This is useful for automating user interactions with JavaScript dialogs.

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

--------------------------------

### Save PDF to Disk

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Saves the current page as a PDF file to the specified path. Requires paper dimensions to be set.

```ruby
page.go_to("https://google.com/")
# Save to disk as a PDF
page.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true
```

--------------------------------

### set_viewport

Source: https://github.com/rubycdp/ferrum/blob/main/docs/14-emulation.md

Overrides device screen dimensions and emulates viewport.

```APIDOC
## set_viewport

### Description
Overrides device screen dimensions and emulates viewport.

### Method
Not applicable (SDK method)

### Parameters
#### Options Hash
- **:width** (Integer) - Optional - viewport width. `0` by default
- **:height** (Integer) - Optional - viewport height. `0` by default
- **:scale_factor** (Float) - Optional - device scale factor. `0` by default
- **:mobile** (Boolean) - Optional - whether to emulate mobile device. `false` by default

### Request Example
```ruby
page.set_viewport(width: 1000, height: 600, scale_factor: 3)
```
```

--------------------------------

### Save Full Page Screenshot as Base64 with Quality

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Captures a full-page screenshot, encodes it as Base64, and reduces the quality. Useful for reducing data size when not saving to disk.

```ruby
# Save to Base64 the whole page not only viewport and reduce quality
page.screenshot(full: true, quality: 60, encoding: :base64) # "iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAYAAAC6uhUNAAAAAXNSR0IArs4c6Q..."
```

--------------------------------

### Set Browser Window Position - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Set the browser window's position using the `position` attribute with `:left` and `:top` options.

```ruby
browser.position = { left: 10, top: 20 }
```

--------------------------------

### Wait for Download Completion - Ruby

Source: https://github.com/rubycdp/ferrum/blob/main/docs/8-downloads.md

Waits for a download to finish. Can be used with or without an explicit action that triggers the download.

```ruby
page.go_to("http://localhost/attachment.pdf")
page.downloads.wait
```

```ruby
page.go_to("http://localhost/page")
page.downloads.wait { page.at_css("#download").click }
```

--------------------------------

### tracing.record

Source: https://github.com/rubycdp/ferrum/blob/main/docs/19-tracing.md

Records a trace and outputs the trace data. If a path is specified, it saves the trace to a file.

```APIDOC
## tracing.record(**options)

### Description
Accepts a block, records a trace, and by default returns trace data from the `Tracing.tracingComplete` event as output. When `path` is specified, returns `true` and stores trace data into a file.

### Method
`tracing.record`

### Parameters
#### Options (`Hash`)
- **:path** (`String`) - Save data on the disk, `nil` by default.
- **:encoding** (`Symbol`) - `:base64` | `:binary` - Encode output as Base64 or plain text. `:binary` by default.
- **:timeout** (`Float`) - Wait until file streaming finishes in the specified time or raise an error, defaults to `nil`.
- **:screenshots** (`Boolean`) - Capture screenshots in the trace, `false` by default.
- **:trace_config** (`Hash<String, Object>`) - Config for [trace](https://chromedevtools.github.io/devtools-protocol/tot/Tracing/#type-TraceConfig). For categories, see [getCategories](https://chromedevtools.github.io/devtools-protocol/tot/Tracing/#method-getCategories). Only one trace config can be active at a time per browser.

### Request Example
```ruby
page.tracing.record(path: "trace.json") do
  page.go_to("https://www.google.com")
end
```

### Response
#### Success Response
- `String` - Trace data if `path` is not specified.
- `true` - If `path` is specified and the trace is saved successfully.

#### Response Example
```json
{
  "trace_data": "...base64_encoded_trace..."
}
```

```json
{
  "success": true
}
```
```

--------------------------------

### Emulate Network Conditions

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Activates emulation of network conditions such as connection type, latency, and throughput. Use this to test how your application behaves under different network constraints.

```ruby
page.network.emulate_network_conditions(connection_type: "cellular2g")
page.go_to("https://github.com/")
```

--------------------------------

### Authorize Server or Proxy Requests

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Provides credentials for server or proxy authorization. Requires a block to handle the authenticated request, allowing or denying it.

```ruby
page.network.authorize(user: "login", password: "pass") { |req| req.continue }
page.go_to("http://example.com/authenticated")
puts page.network.status # => 200
puts page.body # => Welcome, authenticated client
```

--------------------------------

### add_style_tag(**options)

Source: https://github.com/rubycdp/ferrum/blob/main/docs/13-javascript.md

Adds a style tag to the page. Options can include URL, path, or content.

```APIDOC
## add_style_tag(**options)

### Description
Adds a style tag to the page.

### Parameters
* options `Hash`
  * :url `String`
  * :path `String`
  * :content `String`

### Request Example
```ruby
page.add_style_tag(content: "h1 { font-size: 40px; }") # => true
```
```

--------------------------------

### Keyboard Control

Source: https://github.com/rubycdp/ferrum/blob/main/docs/10-mouse-keyboard.md

Methods for simulating keyboard actions like key presses, typing, and modifier keys.

```APIDOC
## Keyboard API

### `page.keyboard.down(key)`

Dispatches a keydown event.

* **key** (String | Symbol) - Name of the key (e.g., "a", :enter, :backspace).

### `page.keyboard.up(key)`

Dispatches a keyup event.

* **key** (String | Symbol) - Name of the key (e.g., "b", :enter, :backspace).

### `page.keyboard.type(*keys)`

Sends a keydown, keypress/input, and keyup event for each character in the text.

* **keys** (String | Array<String> | Array<Symbol>) - Text to type into a focused element (e.g., "Hello World", [:Shift, "s"], "tring").

### `page.keyboard.modifiers(keys)`

Returns a bitfield for a given set of keys.

* **keys** (Array<Symbol>) - Array of modifier keys (e.g., [:alt, :ctrl, :command, :shift]).

## Examples

```ruby
# 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
page.keyboard.down(:Shift)
page.keyboard.type("h", "e", "l", "l", "o")
page.keyboard.up(:Shift)
```
```

--------------------------------

### Set Viewport Dimensions

Source: https://github.com/rubycdp/ferrum/blob/main/docs/14-emulation.md

Overrides device screen dimensions and emulates viewport. Options include width, height, scale_factor, and mobile emulation.

```ruby
page.set_viewport(width: 1000, height: 600, scale_factor: 3)
```

--------------------------------

### Set Headers

Source: https://github.com/rubycdp/ferrum/blob/main/docs/12-headers.md

Clears all existing headers and sets new ones.

```APIDOC
## SET headers(headers)

### Description
Set given headers. Eventually clear all headers and set given ones.

### Method
POST

### Endpoint
page.headers

### Parameters
#### Request Body
- **headers** (Hash) - Required - Key-value pairs for headers, e.g., `"User-Agent" => "Browser"`
```

--------------------------------

### back

Source: https://github.com/rubycdp/ferrum/blob/main/docs/3-navigation.md

Navigates the browser to the previous page in the history.

```APIDOC
## back

### Description
Navigates to the previous page in the browser's history.
```

--------------------------------

### Thread Safety with Independent Contexts

Source: https://github.com/rubycdp/ferrum/blob/main/docs/1-introduction.md

Illustrates thread safety by creating two independent browser contexts, each with its own page. Threads navigate to different URLs and take screenshots, ensuring isolation.

```ruby
browser = Ferrum::Browser.new

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

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

t1.join
t2.join

browser.quit
```

--------------------------------

### Interact with Elements within a Frame

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Demonstrates how to access a frame and then use selectors to find elements within that specific frame. This is crucial for interacting with nested content.

```ruby
page.go_to("https://example.com/page-with-iframe")
frame = page.at_xpath("//iframe").frame # => Frame
frame.at_css("//a[text() = 'Log in']") # => Node
```

--------------------------------

### emulate_network_conditions

Source: https://github.com/rubycdp/ferrum/blob/main/docs/7-network.md

Activates emulation of network conditions. Allows setting offline status, latency, download/upload throughput, and connection type.

```APIDOC
## emulate_network_conditions(**options)

### Description
Activates emulation of network conditions.

### Parameters
#### Options (Hash)
- **:offline** (Boolean) - Optional - Emulate internet disconnection, `false` by default.
- **:latency** (Integer) - Optional - Minimum latency from request sent to response headers received (ms), `0` by default.
- **:download_throughput** (Integer) - Optional - Maximal aggregated download throughput (bytes/sec), `-1` by default, disables download throttling.
- **:upload_throughput** (Integer) - Optional - Maximal aggregated upload throughput (bytes/sec), `-1` by default, disables download throttling.
- **:connection_type** (String) - Optional - Connection type if known, one of: none, cellular2g, cellular3g, cellular4g, bluetooth, ethernet, wifi, wimax, other. `nil` by default.

### Request Example
```ruby
page.network.emulate_network_conditions(connection_type: "cellular2g")
page.go_to("https://github.com/")
```
```

--------------------------------

### pdf

Source: https://github.com/rubycdp/ferrum/blob/main/docs/5-screenshots.md

Saves a PDF on disk or returns it as a base64 string. Supports options for orientation, scale, and paper size.

```APIDOC
#### pdf(\*\*options) : `String` | `Boolean`

### Description
Saves PDF on a disk or returns it as base64.

### Parameters
#### Options (`Hash`)
- `:path` (`String`) - to save a pdf on the disk. `:encoding` will be set to `:binary` automatically
- `:encoding` (`Symbol`) - `:base64` | `:binary` you can set it to return pdf as Base64
- `:landscape` (`Boolean`) - paper orientation. Defaults to false.
- `:scale` (`Float`) - zoom in/out
- `:format` (`symbol`) - standard paper sizes :letter, :legal, :tabloid, :ledger, :A0, :A1, :A2, :A3, :A4, :A5, :A6

- `:paper_width` (`Float`) - set paper width
- `:paper_height` (`Float`) - set paper height
- See other [native options](https://chromedevtools.github.io/devtools-protocol/tot/Page#method-printToPDF) you can pass

### Request Example
```ruby
page.go_to("https://google.com/")
# Save to disk as a PDF
page.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true
```
```

--------------------------------

### Setting Frame Content

Source: https://github.com/rubycdp/ferrum/blob/main/docs/15-frames.md

Replace the entire HTML content of a specific frame.

```APIDOC
## content=

### Description
Sets a content of a given frame.

### Method
`frame.content = html`

### Parameters
#### Request Body
- **html** (String) - Required - The new HTML content for the frame.

### Response
#### Success Response (String)
Returns the updated HTML content of the frame.

### Request Example
```ruby
page.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
frame = page.frames[1]
frame.content = "<html><head></head><body><p>lol</p></body></html>"
frame.body
```
```

--------------------------------

### css

Source: https://github.com/rubycdp/ferrum/blob/main/docs/4-finders.md

Finds all nodes matching a CSS selector. It runs `document.querySelectorAll` within the document or a specified node.

```APIDOC
## css(selector, **options)

### Description
Finds all nodes matching a CSS selector. The method runs `document.querySelectorAll` within the document or provided node.

### Parameters
#### Path Parameters
- **selector** (String) - Required - The CSS selector to search for.
- **options** (Hash) - Optional - Additional options.
  - **:within** (Node | nil) - The node to search within. Defaults to the document.

### Request Example
```ruby
page.css("a[aria-label='Issues you created']")
```

### Response
- **Array<Node>** | **[]** - An array of found nodes, or an empty array if none are found.
```

--------------------------------

### Mouse Control

Source: https://github.com/rubycdp/ferrum/blob/main/docs/10-mouse-keyboard.md

Methods for simulating mouse actions like scrolling, clicking, and moving.

```APIDOC
## Mouse API

### `page.mouse.scroll_to(x, y)`

Scroll page to a given x, y coordinate.

* **x** (Integer) - The pixel along the horizontal axis of the document to display in the upper left.
* **y** (Integer) - The pixel along the vertical axis of the document to display in the upper left.

```ruby
page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
page.mouse.scroll_to(0, 400)
```

### `page.mouse.click(**options)`

Click given coordinates, fires mouse move, down and up events.

* **options** (Hash)
    * **:x** (Integer) - The x-coordinate to click.
    * **:y** (Integer) - The y-coordinate to click.
    * **:delay** (Float) - Delay between mouse down and mouse up events (defaults to 0).
    * **:button** (Symbol) - Mouse button to use (:left or :right, defaults to :left).
    * **:count** (Integer) - Number of clicks (defaults to 1).
    * **:modifiers** (Integer) - Bitfield for key modifiers.

### `page.mouse.down(**options)`

Mouse down for given coordinates.

* **options** (Hash)
    * **:button** (Symbol) - Mouse button to use (:left or :right, defaults to :left).
    * **:count** (Integer) - Number of clicks (defaults to 1).
    * **:modifiers** (Integer) - Bitfield for key modifiers.

### `page.mouse.up(**options)`

Mouse up for given coordinates.

* **options** (Hash)
    * **:button** (Symbol) - Mouse button to use (:left or :right, defaults to :left).
    * **:count** (Integer) - Number of clicks (defaults to 1).
    * **:modifiers** (Integer) - Bitfield for key modifiers.

### `page.mouse.move(x:, y:, steps: 1)`

Mouse move to given x and y coordinates.

* **options** (Hash)
    * **:x** (Integer) - The target x-coordinate.
    * **:y** (Integer) - The target y-coordinate.
    * **:steps** (Integer) - Number of intermediate mousemove events to send (defaults to 1).
```