Skip to content

Commit 1cd3d76

Browse files
routeroute
committed
chore: move documentation to a dedicated website
1 parent a6a59ef commit 1cd3d76

20 files changed

+1526
-1371
lines changed

‎README.md‎

Lines changed: 9 additions & 1371 deletions
Large diffs are not rendered by default.

‎docs/1-introduction.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Introduction
6+
7+
Ferrum is a high-level API to control Chrome in Ruby.
8+
9+
![Ferrum Logo](https://raw.githubusercontent.com/rubycdp/ferrum/main/logo.svg?sanitize=true)
10+
11+
It is Ruby clean and high-level API to Chrome. Runs headless by default, but you
12+
can configure it to run in a headful mode. All you need is Ruby and [Chrome](https://www.google.com/chrome/) or [Chromium](https://www.chromium.org/).
13+
Ferrum connects to the browser by [CDP protocol](https://chromedevtools.github.io/devtools-protocol/) and there's _no_
14+
Selenium/WebDriver/ChromeDriver dependency. The emphasis was made on a raw CDP
15+
protocol because Chrome allows you to do so many things that are barely
16+
supported by WebDriver because it should have consistent design with other
17+
browsers.
18+
19+
## Installation
20+
21+
There's no official Chrome or Chromium package for Linux don't install it this
22+
way because it's either outdated or unofficial, both are bad. Download it from
23+
official source for [Chrome](https://www.google.com/chrome/) or [Chromium](https://www.chromium.org/getting-involved/download-chromium).
24+
Chrome binary should be in the `PATH` or `BROWSER_PATH` and you can pass it as an
25+
option to browser instance see `:browser_path` in
26+
[Customization](/docs/ferrum/customization).
27+
28+
Add this to your `Gemfile` and run `bundle install`.
29+
30+
``` ruby
31+
gem "ferrum"
32+
```
33+
34+
## Docker
35+
36+
:::note
37+
When running in docker as root
38+
:::
39+
40+
```ruby
41+
Ferrum::Browser.new(dockerize: true)
42+
```
43+
44+
Essentially it just sets CLI flags for a browser to make it start. On CI, you can just set `FERRUM_CHROME_DOCKERIZE=true` environment variable, and it will be
45+
passed to all browser instances.
46+
47+
## Quick Start
48+
49+
Navigate to a website and save a screenshot:
50+
51+
```ruby
52+
browser = Ferrum::Browser.new
53+
browser.go_to("https://google.com")
54+
browser.screenshot(path: "google.png")
55+
browser.quit
56+
```
57+
58+
When you work with browser instance Ferrum creates and maintains a default page for you, in fact all the methods above
59+
are sent to the `page` instance that is created in the `default_context` of the `browser` instance. You can interact
60+
with a page created manually and this is preferred:
61+
62+
```ruby
63+
browser = Ferrum::Browser.new
64+
page = browser.create_page
65+
page.go_to("https://google.com")
66+
input = page.at_xpath("//input[@name='q']")
67+
input.focus.type("Ruby headless driver for Chrome", :Enter)
68+
page.at_css("a > h3").text # => "rubycdp/ferrum: Ruby Chrome/Chromium driver - GitHub"
69+
browser.quit
70+
```
71+
72+
Evaluate some JavaScript and get full width/height:
73+
74+
```ruby
75+
browser = Ferrum::Browser.new
76+
page = browser.create_page
77+
page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
78+
width, height = page.evaluate <<~JS
79+
[document.documentElement.offsetWidth,
80+
document.documentElement.offsetHeight]
81+
JS
82+
# => [1024, 1931]
83+
browser.quit
84+
```
85+
86+
Do any mouse movements you like:
87+
88+
```ruby
89+
# Trace a 100x100 square
90+
browser = Ferrum::Browser.new
91+
page = browser.create_page
92+
page.go_to("https://google.com")
93+
page.mouse
94+
.move(x: 0, y: 0)
95+
.down
96+
.move(x: 0, y: 100)
97+
.move(x: 100, y: 100)
98+
.move(x: 100, y: 0)
99+
.move(x: 0, y: 0)
100+
.up
101+
102+
browser.quit
103+
```
104+
105+
## Clean Up
106+
107+
Closes browser tabs opened by the `Browser` instance.
108+
109+
```ruby
110+
# connect to a long-running Chrome process
111+
browser = Ferrum::Browser.new(url: "http://localhost:9222")
112+
113+
browser.go_to("https://github.com/")
114+
115+
# clean up, lest the tab stays there hanging forever
116+
browser.reset
117+
118+
browser.quit
119+
```
120+
121+
## Thread safety
122+
123+
Ferrum is fully thread-safe. You can create one browser or a few as you wish and
124+
start playing around using threads. Example below shows how to create a few pages
125+
which share the same context. Context is similar to an incognito profile but you
126+
can have more than one, think of it like it's independent browser session:
127+
128+
```ruby
129+
browser = Ferrum::Browser.new
130+
context = browser.contexts.create
131+
132+
t1 = Thread.new(context) do |c|
133+
page = c.create_page
134+
page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
135+
page.screenshot(path: "t1.png")
136+
end
137+
138+
t2 = Thread.new(context) do |c|
139+
page = c.create_page
140+
page.go_to("https://www.google.com/search?q=Ruby+static+typing")
141+
page.screenshot(path: "t2.png")
142+
end
143+
144+
t1.join
145+
t2.join
146+
147+
context.dispose
148+
browser.quit
149+
```
150+
151+
or you can create two independent contexts:
152+
153+
```ruby
154+
browser = Ferrum::Browser.new
155+
156+
t1 = Thread.new(browser) do |b|
157+
context = b.contexts.create
158+
page = context.create_page
159+
page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
160+
page.screenshot(path: "t1.png")
161+
context.dispose
162+
end
163+
164+
t2 = Thread.new(browser) do |b|
165+
context = b.contexts.create
166+
page = context.create_page
167+
page.go_to("https://www.google.com/search?q=Ruby+static+typing")
168+
page.screenshot(path: "t2.png")
169+
context.dispose
170+
end
171+
172+
t1.join
173+
t2.join
174+
175+
browser.quit
176+
```
177+
178+
## Development
179+
180+
After checking out the repo, run `bundle install` to install dependencies.
181+
182+
Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will
183+
allow you to experiment.
184+
185+
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
186+
version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
187+
push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
188+
189+
190+
## Contributing
191+
192+
Bug reports and pull requests are welcome on [GitHub](https://github.com/rubycdp/ferrum).

‎docs/10-mouse-keyboard.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
# Mouse & Keyboard
6+
7+
## Mouse
8+
9+
`page.mouse`
10+
11+
#### scroll_to(x, y)
12+
13+
Scroll page to a given x, y
14+
15+
* x `Integer` the pixel along the horizontal axis of the document that you
16+
want displayed in the upper left
17+
* y `Integer` the pixel along the vertical axis of the document that you want
18+
displayed in the upper left
19+
20+
```ruby
21+
page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
22+
page.mouse.scroll_to(0, 400)
23+
```
24+
25+
#### click(\*\*options) : `Mouse`
26+
27+
Click given coordinates, fires mouse move, down and up events.
28+
29+
* options `Hash`
30+
* :x `Integer`
31+
* :y `Integer`
32+
* :delay `Float` defaults to 0. Delay between mouse down and mouse up events
33+
* :button `Symbol` :left | :right, defaults to :left
34+
* :count `Integer` defaults to 1
35+
* :modifiers `Integer` bitfield for key modifiers. See`keyboard.modifiers`
36+
37+
#### down(\*\*options) : `Mouse`
38+
39+
Mouse down for given coordinates.
40+
41+
* options `Hash`
42+
* :button `Symbol` :left | :right, defaults to :left
43+
* :count `Integer` defaults to 1
44+
* :modifiers `Integer` bitfield for key modifiers. See`keyboard.modifiers`
45+
46+
#### up(\*\*options) : `Mouse`
47+
48+
Mouse up for given coordinates.
49+
50+
* options `Hash`
51+
* :button `Symbol` :left | :right, defaults to :left
52+
* :count `Integer` defaults to 1
53+
* :modifiers `Integer` bitfield for key modifiers. See`keyboard.modifiers`
54+
55+
#### move(x:, y:, steps: 1) : `Mouse`
56+
57+
Mouse move to given x and y.
58+
59+
* options `Hash`
60+
* :x `Integer`
61+
* :y `Integer`
62+
* :steps `Integer` defaults to 1. Sends intermediate mousemove events.
63+
64+
## Keyboard
65+
66+
`page.keyboard`
67+
68+
#### down(key) : `Keyboard`
69+
70+
Dispatches a keydown event.
71+
72+
* key `String` | `Symbol` Name of key such as "a", :enter, :backspace
73+
74+
#### up(key) : `Keyboard`
75+
76+
Dispatches a keyup event.
77+
78+
* key `String` | `Symbol` Name of key such as "b", :enter, :backspace
79+
80+
#### type(\*keys) : `Keyboard`
81+
82+
Sends a keydown, keypress/input, and keyup event for each character in the text.
83+
84+
* text `String` | `Array<String> | Array<Symbol>` A text to type into a focused
85+
element, `[:Shift, "s"], "tring"`
86+
87+
#### modifiers(keys) : `Integer`
88+
89+
Returns bitfield for a given keys
90+
91+
* keys `Array<Symbol>` :alt | :ctrl | :command | :shift
92+
93+
## Examples
94+
95+
```ruby
96+
# Type text into an input
97+
page.go_to("https://google.com")
98+
input = page.at_css("input[name='q']")
99+
input.focus
100+
page.keyboard.type("Hello World")
101+
102+
# Press Enter
103+
page.keyboard.type(:Enter)
104+
105+
# Use keyboard shortcuts
106+
page.keyboard.down(:Shift)
107+
page.keyboard.type("h", "e", "l", "l", "o")
108+
page.keyboard.up(:Shift)
109+
```

‎docs/11-cookies.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
sidebar_position: 11
3+
---
4+
5+
# Cookies
6+
7+
`page.cookies`
8+
9+
#### all : `Hash<String, Cookie>`
10+
11+
Returns cookies hash
12+
13+
```ruby
14+
page.cookies.all # => {"NID"=>#<Ferrum::Cookies::Cookie:0x0000558624b37a40 @attributes={"name"=>"NID", "value"=>"...", "domain"=>".google.com", "path"=>"/", "expires"=>1583211046.575681, "size"=>178, "httpOnly"=>true, "secure"=>false, "session"=>false}>}
15+
```
16+
17+
#### \[\](value) : `Cookie`
18+
19+
Returns cookie
20+
21+
* value `String`
22+
23+
```ruby
24+
page.cookies["NID"] # => <Ferrum::Cookies::Cookie:0x0000558624b67a88 @attributes={"name"=>"NID", "value"=>"...", "domain"=>".google.com", "path"=>"/", "expires"=>1583211046.575681, "size"=>178, "httpOnly"=>true, "secure"=>false, "session"=>false}>
25+
```
26+
27+
#### set(value) : `Boolean`
28+
29+
Sets a cookie
30+
31+
* value `Hash`
32+
* :name `String`
33+
* :value `String`
34+
* :domain `String`
35+
* :expires `Integer`
36+
* :samesite `String`
37+
* :httponly `Boolean`
38+
39+
```ruby
40+
page.cookies.set(name: "stealth", value: "omg", domain: "google.com") # => true
41+
```
42+
43+
* value `Cookie`
44+
45+
```ruby
46+
nid_cookie = page.cookies["NID"] # => <Ferrum::Cookies::Cookie:0x0000558624b67a88>
47+
page.cookies.set(nid_cookie) # => true
48+
```
49+
50+
#### remove(\*\*options) : `Boolean`
51+
52+
Removes given cookie
53+
54+
* options `Hash`
55+
* :name `String`
56+
* :domain `String`
57+
* :url `String`
58+
59+
```ruby
60+
page.cookies.remove(name: "stealth", domain: "google.com") # => true
61+
```
62+
63+
#### clear : `Boolean`
64+
65+
Removes all cookies for current page
66+
67+
```ruby
68+
page.cookies.clear # => true
69+
```
70+
71+
#### store(path) : `Boolean`
72+
73+
Stores all cookies of current page in a file.
74+
75+
```ruby
76+
# Cookies are saved into cookies.yml
77+
page.cookies.store # => 15657
78+
```
79+
80+
#### load(path) : `Boolean`
81+
82+
Loads all cookies from the file and sets them for current page.
83+
84+
```ruby
85+
# Cookies are loaded from cookies.yml
86+
page.cookies.load # => true
87+
```

0 commit comments

Comments
 (0)