Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
01869ab
feat(timeout): bound go_to, refresh and scripts by a single Ferrum::D…
route Nov 15, 2026
f1d8223
ref(utils): replace IVar, MVar and Event with Utils::Cell, wait for t…
route Nov 15, 2026
4ba6658
ref(client): require an explicit timeout on synchronous client commands
route Nov 16, 2026
124bbd6
feat(timeout): bound a group of calls with Deadline.within and send n…
route Nov 16, 2026
31079d3
test(deadline): stop asserting a float against the exact budget it wa…
route Nov 16, 2026
1dda217
ref(client): make protocol_timeout an internal constant and drop the …
route Nov 16, 2026
bf60a3b
ref(utils): move Cell and AwaitableMap into Utils::Concurrency
route Nov 16, 2026
d51248c
fix(downloads): don't mark a download in flight as finished when wait…
route Nov 16, 2026
c055ecf
fix(client): give event callbacks ids that survive another one being …
route Nov 16, 2026
a8b5a82
fix(options): keep the fraction of FERRUM_DEFAULT_TIMEOUT
route Nov 16, 2026
0736ac5
ref(page): rename wait to navigation_wait and take it off Page#command
route Nov 16, 2026
4fbc6e2
docs(changelog): note page.idle and the targets snapshot
route Nov 16, 2026
c1ec9f9
chore(sig): drop unused Concurrent IVar and Event signatures and a du…
route Nov 17, 2026
c643a72
ref(client): move Subscriber to Utils::Concurrency::Dispatcher with l…
route Nov 17, 2026
57189df
ref(concurrency): move Cell, AwaitableMap and Dispatcher out of Utils
route Nov 17, 2026
f9c2928
feat(timeout): share one timeout across the commands click, type, mov…
route Nov 17, 2026
f4c1dd0
feat(timeout): add timeout: to keyboard.type, node.type and mouse.move
route Nov 18, 2026
d9948ba
fix(page): raise from go_to once the enclosing Deadline.within has ru…
route Nov 18, 2026
a070041
fix(options): warn that protocol_timeout is ignored instead of droppi…
route Nov 18, 2026
ab655fb
fix(client): reject the removed wait: and async: on commands instead …
route Nov 18, 2026
e3f8563
fix(mouse): take the deprecated wait: on up and down as navigation_wait:
route Nov 18, 2026
f7bcb2b
fix(keyboard): release held modifiers after the enclosing Deadline.wi…
route Nov 18, 2026
d0c7d26
perf(contexts): look a target up by id with Context#target instead of…
route Nov 18, 2026
a8fb13e
docs(command): describe Target#command and Worker#command without the…
route Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
## [Unreleased](https://github.com/rubycdp/ferrum/compare/v0.20.1...main) ##

### Added
- `Ferrum::Deadline.within(seconds) { ... }` bounds every call the block makes with one budget, `page.go_to`, `cookies`
and `evaluate` included. `go_to` raises `NavigationTimeoutError` once it runs out, whatever `on_timeout` is
- `timeout:` on `go_to`, `refresh`, `back`, `forward`, `click` and `wait_for_navigation` bounds the whole call with a single
`Ferrum::Deadline`
- `context.target(id)` returns the context's target with that id
- `timeout:` on `keyboard.type`, `node.type` and `mouse.move` bounds all the keys or steps together, the page `timeout`
by default, raise it for a long text
- `cookies[name, domain:, path:]` picks one of the cookies sharing a name
- `context.cookies` with every cookie in the context whatever its domain, `browser.cookies` is the default context's
- `network.emulate(user_agent:, accept_language:, platform:, metadata:)` overrides what the page reports in the request
Expand All @@ -10,6 +17,22 @@
pending, when the page doesn't load in time

### Changed
- `client.command` needs a `timeout:` and has no `async: true`, use `client.notify` to send without waiting, and
`browser.command` defaults to the browser's `timeout`
- `:protocol_timeout` is ignored and warns, as do `browser.protocol_timeout`, `browser.protocol_timeout=` and
`FERRUM_PROTOCOL_TIMEOUT`: internal commands have a fixed 5 second timeout and the connection is closed once a
write to the browser stalls for 30 seconds
- Creating pages and contexts follows `timeout`
- `wait:` of `click`, `mouse.up` and `mouse.down` is renamed to `navigation_wait:`, `wait:` still works and warns
- `Mouse::CLICK_WAIT` and `Page::GOTO_WAIT` are merged into `Page::NAVIGATION_WAIT`, set by `FERRUM_NAVIGATION_WAIT`,
`FERRUM_CLICK_WAIT` and `FERRUM_GOTO_WAIT` still work and warn
- `page.command` doesn't take `wait:` anymore, wrap it in `page.wait_for_navigation` to wait for a navigation it starts.
Passing `wait:` or `async:` to a command raises `ArgumentError`, they would be sent to the browser as parameters
- `page.event` is `page.idle` and holds a `Ferrum::Concurrency::Cell`, not a `Concurrent::Event`
- `browser.targets` and `context.targets` return a copy of the hash, it doesn't follow the targets that come and go
- `go_to`, `refresh` and the script methods no longer restart the timeout for each step, one `timeout` covers the whole call
- `click`, `mouse.move`, `keyboard.type`, `back`, `forward`, `wait_for_selector` and node scripts share one `timeout` across the
commands they send, they restarted it for each
- `page.on(:request)`, `on(:auth)` and `on(:dialog)` callbacks form a chain: they run in order and the rest are skipped
once one continues, responds to, aborts, accepts or dismisses, and an unhandled request is continued. They receive
only the object, not `index` and `total`, use `handled?` to check whether a previous callback took it. A callback
Expand Down
13 changes: 10 additions & 3 deletions docs/10-mouse-keyboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,9 @@ Click given coordinates, fires mouse move, down and up events.
* :x `Integer`
* :y `Integer`
* :delay `Float` defaults to 0. Delay between mouse down and mouse up events
* :wait `Numeric` defaults to `Mouse::CLICK_WAIT`. Seconds to watch for a navigation started by the click, then
* :navigation_wait `Numeric` defaults to `Page::NAVIGATION_WAIT`. Seconds to watch for a navigation started by the click, then
wait for it to load. `0` returns right after the click.
* :timeout `Numeric` how long the click and the page load it starts may take together, the page timeout by default
* :button `Symbol` :left | :right, defaults to :left
* :count `Integer` defaults to 1
* :modifiers `Integer` bitfield for key modifiers. See `keyboard.modifiers`.
Expand All @@ -56,8 +57,11 @@ Mouse up for given coordinates.
* :count `Integer` defaults to 1
* :modifiers `Integer` bitfield for key modifiers. See `keyboard.modifiers`.
If omitted, uses the keys held by `keyboard.hold`, or none outside of it
* :navigation_wait `Numeric` seconds to watch for a navigation started by releasing the button, then wait for it
to load, defaults to 0
* :timeout `Numeric` how long the event and the page load it starts may take together, the page timeout by default

#### move(x:, y:, steps: 1, modifiers: nil) : `Mouse`
#### move(x:, y:, steps: 1, modifiers: nil, timeout: nil) : `Mouse`

Mouse move to given x and y.

Expand All @@ -67,6 +71,7 @@ Mouse move to given x and y.
* :steps `Integer` defaults to 1. Sends intermediate mousemove events.
* :modifiers `Integer` bitfield for key modifiers. See `keyboard.modifiers`.
If omitted, uses the keys held by `keyboard.hold`, or none outside of it
* :timeout `Numeric` how long all the steps may take together, the page timeout by default

## Keyboard

Expand All @@ -86,12 +91,14 @@ Dispatches a keyup event.
* key `String` | `Symbol` Name of key such as "b", :enter, :backspace. Raises `ArgumentError` for a modifier,
use `hold` instead

#### type(\*keys) : `Keyboard`
#### type(\*keys, timeout: nil) : `Keyboard`

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

* text `String` | `Array<String> | Array<Symbol>` A text to type into a focused
element, `[:Shift, "s"], "tring"`
* timeout `Numeric` how long typing all the keys may take together, the page timeout by default. Raise it for a long
text

#### hold(\*keys) { } : `Object`

Expand Down
14 changes: 9 additions & 5 deletions docs/18-node.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,10 +111,11 @@ Removes focus from the node.
page.at_css("input[name='q']").focus.blur
```

#### type(\*keys) : `Node`
#### type(\*keys, timeout: nil) : `Node`

Types the keys with the page's keyboard, into whatever is focused, so it's usually chained after `focus` or `click`. See
[keyboard](https://github.com/rubycdp/ferrum#keyboard) for what a key can be.
[keyboard](https://github.com/rubycdp/ferrum#keyboard) for what a key can be. `timeout` bounds typing all the keys together,
the page timeout by default.

```ruby
page.at_css("input[name='q']").focus.type("Ruby", :Enter)
Expand All @@ -135,12 +136,15 @@ moving.
* :position `Symbol` `:top` | `:center`, what the offset is measured from, the top-left corner of the node or its
center, `:top` by default
* :delay `Float` delay between mouse down and mouse up, `0` by default
* :wait `Numeric` seconds to watch for a navigation started by a left click, then wait for it to load,
`Mouse::CLICK_WAIT` by default. Ignored for `:right` and `:double`. `0` returns right after the click.
* :navigation_wait `Numeric` seconds to watch for a navigation started by a left click, then wait for it to load,
`Page::NAVIGATION_WAIT` by default. Ignored for `:right` and `:double`. `0` returns right after the click.
* :timeout `Numeric` how long finding the node's position, the click and the page load it starts may take together,
the page timeout by default

```ruby
page.at_css("a").click
page.at_css("a").click(wait: 0)
page.at_css("a").click(navigation_wait: 0)
page.at_css("a").click(timeout: 30)
page.at_css("a").click(mode: :right)
page.at_css("a").click(keys: [:ctrl, :shift])
page.at_css("canvas").click(offset: { x: 10, y: 20 })
Expand Down
27 changes: 25 additions & 2 deletions docs/2-customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,11 @@ Ferrum::Browser.new(options)
written to it, see [Logging](#logging).
* `: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) - The number of seconds we'll wait for a response when
communicating with browser. Default is 5.
* `:timeout` (Numeric) - How long a call waits for the browser, in seconds, `FERRUM_DEFAULT_TIMEOUT` or 5 by
default. `go_to`, `refresh` and `wait_for_navigation` wait for the page to load within it. A call that only sends
commands, like `evaluate` or `at_css`, waits for the browser's answer. A call that runs out raises
`Ferrum::TimeoutError`. Pass `timeout:` to `go_to`, `refresh` or `wait_for_navigation` to change it for one
call, or wrap calls in `Ferrum::Deadline.within` to bound them together, see [Timeouts](#timeouts).
* `:js_errors` (Boolean) - Deprecated, will be removed in 0.22. When true, JavaScript errors get re-raised in
Ruby. Uncaught exceptions are in the [console](/docs/ferrum/javascript#console), use
`page.console.select { |m| m.source == :exception }` or `page.on(:console)` instead.
Expand Down Expand Up @@ -185,3 +188,23 @@ Ferrum::Browser.new(browser_path: "/Applications/Google Chrome.app/Contents/MacO
# Add custom browser options
Ferrum::Browser.new(browser_options: { "disable-web-security" => nil })
```

## Timeouts

Every call that talks to the browser can raise `Ferrum::TimeoutError`, and `Ferrum::DeadBrowserError` when the browser is
gone, even where nothing looks like a request, like `page.cookies.each`. Each call waits at most the `:timeout` option.

To bound a group of calls by one budget, wrap them in `Ferrum::Deadline.within`. Every call made in the block by the
same thread shares what is left of it, and a call can only shorten it, never extend it:

```ruby
Ferrum::Deadline.within(10) do
page.go_to("https://example.com")
page.cookies.to_a
page.evaluate("document.title")
end
# => raises Ferrum::TimeoutError from the first call that runs out of the 10 seconds
```

Blocks nest, the shorter budget wins. Other threads, such as event callbacks, don't inherit it, open a block of their own
there.
32 changes: 22 additions & 10 deletions docs/3-navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,38 +12,49 @@ Navigate page to.
configuring driver.
* options `Hash`
* :on_timeout `Symbol` What to do when the timeout is reached: `:ignore` (default) returns `nil`,
`:raise` raises `Ferrum::NavigationTimeoutError` naming the requests still pending.
`:raise` raises `Ferrum::NavigationTimeoutError` naming the requests still pending. It raises with `:ignore` too
once an enclosing `Ferrum::Deadline.within` has run out.
* :timeout `Numeric` How long the whole navigation may take, sending the request and loading the page together,
the page timeout by default.

```ruby
page.go_to("https://github.com/")
page.go_to("https://github.com/", on_timeout: :raise)
page.go_to("https://github.com/", timeout: 10)
```

#### back
#### back(timeout: nil)

Navigate to the previous page in history.

* timeout `Numeric` how long the history lookup and the page load may take together, the page timeout by default

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

#### forward
#### forward(timeout: nil)

Navigate to the next page in history.

* timeout `Numeric` how long the history lookup and the page load may take together, the page timeout by default

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

#### refresh
#### refresh(timeout: nil)

Reload current page.

* timeout `Numeric` how long the whole reload may take, the page timeout by default

```ruby
page.go_to("https://github.com/")
page.refresh
Expand All @@ -58,22 +69,23 @@ page.go_to("https://github.com/")
page.stop
```

#### wait_for_navigation(wait = 0.1) { } : `Boolean`
#### wait_for_navigation(navigation_wait = 0.1, timeout: nil) { } : `Boolean`

Runs the block and, if it starts a navigation within `wait` seconds, waits for the new page to load. Returns `false`
if it doesn't load within the page timeout. `click` already does this, use it for navigations started from
Runs the block and, if it starts a navigation within `navigation_wait` seconds, waits for the new page to load. Returns `false`
if it doesn't load within `timeout`. `click` already does this, use it for navigations started from
JavaScript.

* wait `Numeric` seconds to watch for a navigation after the block, `FERRUM_CLICK_WAIT` or `0.1` by default
* navigation_wait `Numeric` seconds to watch for a navigation after the block, `FERRUM_NAVIGATION_WAIT` or `0.1` by default
* timeout `Numeric` how long the block and the navigation may take together, the page timeout by default

```ruby
page.wait_for_navigation { page.at_css("a").evaluate("this.click()") } # => true
page.url # => the link's page
```

#### wait_for_navigation!(wait = 0.1) { }
#### wait_for_navigation!(navigation_wait = 0.1, timeout: nil) { }

Same as `wait_for_navigation`, but raises `Ferrum::TimeoutError` if the new page doesn't load within the page timeout.
Same as `wait_for_navigation`, but raises `Ferrum::TimeoutError` if the new page doesn't load within `timeout`, the page timeout by default.

```ruby
page.wait_for_navigation! { page.at_css("a").evaluate("this.click()") }
Expand Down
5 changes: 4 additions & 1 deletion lib/ferrum.rb
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,13 @@

require "concurrent-ruby"
require "ferrum/version"
require "ferrum/utils/event"
require "ferrum/utils/thread"
require "ferrum/utils/platform"
require "ferrum/utils/elapsed_time"
require "ferrum/deadline"
require "ferrum/concurrency/cell"
require "ferrum/concurrency/awaitable_map"
require "ferrum/concurrency/dispatcher"
require "ferrum/utils/attempt"
require "ferrum/utils/deprecate"
require "ferrum/errors"
Expand Down
12 changes: 12 additions & 0 deletions lib/ferrum/accessibility.rb
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ def node_for(node)
# @param [Boolean] fetch_relatives
# @return [Array<AXNode>]
#
# @raise [TimeoutError]
#
def partial_tree(node:, fetch_relatives: false)
nodes = node.page.command("Accessibility.getPartialAXTree",
nodeId: node.node_id,
Expand All @@ -50,6 +52,8 @@ def partial_tree(node:, fetch_relatives: false)
# @param [String, nil] frame_id
# @return [Array<AXNode>]
#
# @raise [TimeoutError]
#
def snapshot(depth: nil, frame_id: nil)
params = { depth: depth, frameId: frame_id }.compact
build(@page.command("Accessibility.getFullAXTree", **params)["nodes"])
Expand All @@ -63,6 +67,8 @@ def snapshot(depth: nil, frame_id: nil)
# @param [Ferrum::Node, nil] node Scope the query to this node's subtree.
# @return [Array<AXNode>]
#
# @raise [TimeoutError]
#
def query(name: nil, role: nil, node: nil)
page = node ? node.page : @page
params = { accessibleName: name, role: role }.compact
Expand All @@ -76,6 +82,8 @@ def query(name: nil, role: nil, node: nil)
# @param [String, nil] frame_id
# @return [AXNode, nil]
#
# @raise [TimeoutError]
#
def root(frame_id: nil)
params = { depth: 1, frameId: frame_id }.compact
build(@page.command("Accessibility.getFullAXTree", **params)["nodes"]).first
Expand All @@ -84,6 +92,8 @@ def root(frame_id: nil)
# Enables the Accessibility domain, activating live AX tree change events.
#
# @return [self]
#
# @raise [TimeoutError]
def enable
@page.command("Accessibility.enable")
self
Expand All @@ -92,6 +102,8 @@ def enable
# Disables the Accessibility domain.
#
# @return [self]
#
# @raise [TimeoutError]
def disable
@page.command("Accessibility.disable")
self
Expand Down
44 changes: 34 additions & 10 deletions lib/ferrum/browser.rb
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,8 @@ class Browser

attr_reader :client, :process, :contexts, :options

delegate %i[timeout timeout= protocol_timeout protocol_timeout=
base_url base_url= default_user_agent default_user_agent= extensions add_extension] => :options
delegate %i[command] => :client
delegate %i[timeout timeout= protocol_timeout protocol_timeout= base_url base_url= default_user_agent
default_user_agent= extensions add_extension] => :options

#
# Initializes the browser.
Expand Down Expand Up @@ -89,13 +88,11 @@ class Browser
# changes.
#
# @option options [Numeric] :timeout (5)
# The number of seconds we'll wait for a response when communicating
# with the browser: navigations, JS evaluation, DOM queries, dispatching input, etc.
#
# @option options [Numeric] :protocol_timeout (5)
# The number of seconds we'll wait for an individual internal CDP
# bookkeeping call to respond, e.g. `Target.createTarget`,
# `Target.attachToTarget`. These normally resolve in milliseconds.
# How long a call waits for the browser, in seconds: navigations, JS evaluation, DOM queries, dispatching
# input, etc. `go_to`, `refresh` and `wait_for_navigation` wait for the page to load within it. A call that
# only sends commands waits for the browser's answer. A call that runs out raises {TimeoutError}.
# `FERRUM_DEFAULT_TIMEOUT` sets the default. Pass `timeout:` to `go_to`, `refresh` or `wait_for_navigation` to
# change it for one call, or wrap calls in {Deadline.within} to bound them together.
#
# @option options [Boolean] :js_errors
# Deprecated, will be removed in Ferrum 0.22. When true, JavaScript
Expand Down Expand Up @@ -168,6 +165,8 @@ def initialize(options = nil)
# @return [Ferrum::Page]
# Created page.
#
# @raise [TimeoutError]
#
def create_page(new_context: false, proxy: nil)
page = if new_context || proxy
params = {}
Expand Down Expand Up @@ -195,6 +194,8 @@ def create_page(new_context: false, proxy: nil)
#
# Closes browser tabs opened by the `Browser` instance.
#
# @raise [TimeoutError]
#
# @example
# # connect to a long-running Chrome process
# browser = Ferrum::Browser.new(url: 'http://localhost:9222')
Expand Down Expand Up @@ -256,11 +257,34 @@ def close
command("Browser.close")
end

#
# Sends a CDP command to the browser.
#
# @param [String] method
# The CDP method name, e.g. `"Browser.getVersion"`.
#
# @param [Numeric, Deadline, nil] timeout
# How long to wait for the response, the browser's `timeout` by default.
#
# @param [Hash] params
# The command's parameters.
#
# @return [Hash]
# The command's result.
#
# @raise [TimeoutError]
#
def command(method, timeout: nil, **params)
client.command(method, timeout: timeout || self.timeout, **params)
end

#
# Gets the version information from the browser.
#
# @return [VersionInfo]
#
# @raise [TimeoutError]
#
# @since 0.13
#
def version
Expand Down
Loading
Loading