Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
otherwise stops sending once the user agent is overridden
- `go_to(url, on_timeout: :raise)` raises `NavigationTimeoutError`, a `TimeoutError` naming the requests still
pending, when the page doesn't load in time
- `browser.off`, `window_bounds`, `window_bounds=`, `tracing`, `activate` and `document_size` reach the page like the
rest of its methods

### Changed
- `client.command` needs a `timeout:` and has no `async: true`, use `client.notify` to send without waiting, and
Expand Down
13 changes: 13 additions & 0 deletions docs/1-introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,19 @@ thread = browser.quit(wait: false)
thread.join # only needed if you must wait for cleanup to finish, e.g. before reusing a fixed port
```

## Raw CDP

Most `Browser` methods are shortcuts to its default page, `browser.on` included, but `browser.command` isn't: it
talks to the browser itself, for the `Browser.*`, `Target.*` and other browser-wide domains. Send page commands,
like `Page.*`, `Runtime.*` or `DOM.*`, through the page:

```ruby
browser.command("Browser.getVersion")

browser.page.command("Runtime.evaluate", expression: "1 + 1")
browser.on("Page.frameNavigated") { |params| puts params["frame"]["url"] } # same as browser.page.on
```

## Thread safety

Ferrum is fully thread-safe. You can create one browser or a few as you wish and
Expand Down
10 changes: 6 additions & 4 deletions lib/ferrum/browser.rb
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,15 @@ class Browser
wait_for_navigation wait_for_navigation!
at_css at_xpath css xpath wait_for_selector current_url current_title url title
body doctype content=
headers network console accessibility downloads
headers network console accessibility downloads tracing
mouse keyboard
screenshot pdf mhtml viewport_size device_pixel_ratio
screenshot pdf mhtml viewport_size device_pixel_ratio document_size
start_screencast stop_screencast
frames frame_by main_frame
evaluate evaluate_handle execute isolated_world
add_script_tag add_style_tag bypass_csp
evaluate_on_new_document remove_script_on_new_document
on position position=
on off position position= window_bounds window_bounds= activate
playback_rate playback_rate=
disable_javascript set_viewport resize] => :page

Expand Down Expand Up @@ -260,7 +260,9 @@ def close
end

#
# Sends a CDP command to the browser.
# Sends a CDP command to the browser itself, not to the default page like
# most other `Browser` methods, {#on} included. Use `page.command` for page
# domains such as `Page`, `Runtime` or `DOM`.
#
# @param [String] method
# The CDP method name, e.g. `"Browser.getVersion"`.
Expand Down
2 changes: 0 additions & 2 deletions sig/ferrum/deadline.rbs
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ module Ferrum

def expired?: () -> bool

protected

attr_reader at: Float
end
end
2 changes: 0 additions & 2 deletions sig/ferrum/page.rbs
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,6 @@ module Ferrum

def window_id: () -> ::Integer

def set_window_bounds: (Hash[Symbol, (::Integer | String)] bounds) -> Hash[String, untyped]

def command: (String method, ?slowmoable: bool, ?timeout: (::Numeric | Deadline)?, **untyped) -> Hash[String, untyped]

def on: (:dialog) { (Dialog) -> void } -> Integer
Expand Down
45 changes: 45 additions & 0 deletions spec/browser_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -1156,4 +1156,49 @@ def proxy_tunnel(socket, request, browser_url)
expect(browser.accessibility).to be_a(Ferrum::Accessibility)
end
end

describe "#tracing" do
it "returns the tracing of the page" do
expect(browser.tracing).to be(browser.page.tracing)
end
end

describe "#off" do
it "unsubscribes from the page event" do
removed = []
kept = []
id = browser.on("Runtime.consoleAPICalled") { |params| removed << params.dig("args", 0, "value") }
browser.on("Runtime.consoleAPICalled") { |params| kept << params.dig("args", 0, "value") }
browser.evaluate("console.log('first')")
wait_for { kept }.to eq(["first"])

browser.off("Runtime.consoleAPICalled", id)
browser.evaluate("console.log('second')")

wait_for { kept }.to eq(%w[first second])
expect(removed).to eq(["first"])
end
end

describe "#document_size" do
it "returns the scroll size of the page" do
browser.content = %(<div style="width: 2000px; height: 3000px"></div>)

expect(browser.document_size).to eq(browser.page.document_size)
end
end

describe "#window_bounds" do
it "returns the window bounds of the page" do
browser.window_bounds = { width: 800, height: 600 }

expect(browser.window_bounds).to include("width" => 800, "height" => 600)
end
end

describe "#activate" do
it "brings the page to the front" do
expect(browser.activate).to be(true)
end
end
end
Loading