ferrum 0.6.1 → 0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f5179f765dbfb25cfbb1512958c5c4e8d2e8b486d48973bd2d2922389f74f8f
-  data.tar.gz: 47f2b8cc7afc75c06dffe27fae3e3a54558c86579c412d6806e9713e3282c0e8
+  metadata.gz: c605388d1ea1a0f54f5f1ef24e56a93b60d109ec6eb02798d9de606cd54c29ef
+  data.tar.gz: a0cb3328ad526e51beaefb5eb8140659b1dd277acda5305f46464200d02ed24a
 SHA512:
-  metadata.gz: 9566908dab8979128138801a7b105905e0198e4873b9c668e231078108a31cc6e7586ab4c4405c527908ffb9557d255bc9a02b6e878392946b2eb1d79f8cc0a0
-  data.tar.gz: 4b4fa5c411f0831a0fbd80ac880621e0459ff8dc976d828c1b88dfbf5f05023a096b2a6696269048416b7bdcef1f34f8d360a841e0798bb936277a96b4da4929
+  metadata.gz: c3e44b234a458079b268b7af941af8404a7aa9e6ade2d018ca07fdabcc21518a5d1ad6daafbcdcd3ed7dffe5f94f9b5a4fef36aa1b317178b1604df7f96a8a2b
+  data.tar.gz: 8b4ea9e0c5b0d029d743b1314dba4b6111f87f26ac4cb5c87e1b06d04b9693fc0570908456c4ced0860b07cc748d8ba783b320481d2879ec5df7b65ec70e85ec

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Dmitry Vorotilin
+Copyright (c) 2019-2020 Dmitry Vorotilin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,43 +1,83 @@
-# Ferrum - fearless Ruby Chrome driver
+# Ferrum - high-level API to control Chrome in Ruby
 
-[![Build Status](https://travis-ci.org/route/ferrum.svg?branch=master)](https://travis-ci.org/route/ferrum)
-
-<img align="right" width="95" height="95"
+<img align="right"
+     width="320" height="241"
      alt="Ferrum logo"
-     src="https://raw.githubusercontent.com/route/ferrum/master/logo.svg?sanitize=true">
-
-As simple as Puppeteer, though even simpler.
-
-It is Ruby clean and high-level API to Chrome. Runs headless by default,
-but you can configure it to run in a non-headless mode. All you need is Ruby and
-Chrome/Chromium. Ferrum connects to the browser via DevTools Protocol.
+     src="https://raw.githubusercontent.com/rubycdp/ferrum/master/logo.svg?sanitize=true">
+
+#### As simple as Puppeteer, though even simpler.
+
+It is Ruby clean and high-level API to Chrome. Runs headless by default, but you
+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/). Ferrum connects to the browser by [CDP
+protocol](https://chromedevtools.github.io/devtools-protocol/) and  there's _no_
+Selenium/WebDriver/ChromeDriver dependency. The emphasis was made on a raw CDP
+protocol because Chrome allows you to do so many things that are barely
+supported by WebDriver because it should have consistent design with other
+browsers.
+
+* [Cuprite](https://github.com/rubycdp/cuprite) is a pure Ruby driver for
+[Capybara](https://github.com/teamcapybara/capybara) based on Ferrum. If you are
+going to crawl sites you better use Ferrum or
+[Vessel](https://github.com/rubycdp/vessel) because you crawl, not test.
+
+* [Vessel](https://github.com/rubycdp/vessel) high-level web crawling framework
+based on Ferrum. It looks like [Scrapy](https://scrapy.org/) except that it uses
+a real browser in order to grab data.
+
+Web design by [Evrone](https://evrone.com/), what else
+[we build with Ruby on Rails](https://evrone.com/ruby), what else
+[we do at Evrone](https://evrone.com/cases#case-studies).
+
+
+## Index
+
+* [Install](https://github.com/rubycdp/ferrum#install)
+* [Examples](https://github.com/rubycdp/ferrum#examples)
+* [Docker](https://github.com/rubycdp/ferrum#docker)
+* [Customization](https://github.com/rubycdp/ferrum#customization)
+* [Navigation](https://github.com/rubycdp/ferrum#navigation)
+* [Finders](https://github.com/rubycdp/ferrum#finders)
+* [Screenshots](https://github.com/rubycdp/ferrum#screenshots)
+* [Network](https://github.com/rubycdp/ferrum#network)
+* [Mouse](https://github.com/rubycdp/ferrum#mouse)
+* [Keyboard](https://github.com/rubycdp/ferrum#keyboard)
+* [Cookies](https://github.com/rubycdp/ferrum#cookies)
+* [Headers](https://github.com/rubycdp/ferrum#headers)
+* [JavaScript](https://github.com/rubycdp/ferrum#javascript)
+* [Frames](https://github.com/rubycdp/ferrum#frames)
+* [Frame](https://github.com/rubycdp/ferrum#frame)
+* [Dialog](https://github.com/rubycdp/ferrum#dialog)
+* [Thread safety](https://github.com/rubycdp/ferrum#thread-safety)
+* [Development](https://github.com/rubycdp/ferrum#development)
+* [Contributing](https://github.com/rubycdp/ferrum#contributing)
+* [License](https://github.com/rubycdp/ferrum#license)
 
-Relation to [Cuprite](https://github.com/machinio/cuprite). Cuprite used to have
-this code inside in one form or another but the thing is you don't need capybara
-if you are going to crawl sites. You crawl, not test. Besides that clean
-lightweight API to browser is what Ruby was missing, so here it comes.
-
-If you like this project, please consider to [become a backer](https://www.patreon.com/rferrum) on Patreon.
 
 ## Install
 
 There's no official Chrome or Chromium package for Linux don't install it this
-way because it either will be outdated or unofficial, both are bad. Download it
-from official [source](https://www.chromium.org/getting-involved/download-chromium).
+way because it's either outdated or unofficial, both are bad. Download it from
+official [source](https://www.chromium.org/getting-involved/download-chromium).
 Chrome binary should be in the `PATH` or `BROWSER_PATH` or you can pass it as an
-option to browser instance `:browser_path`.
+option to browser instance see `:browser_path` in
+[Customization](https://github.com/rubycdp/ferrum#customization).
 
-Add this to your Gemfile:
+Add this to your `Gemfile` and run `bundle install`.
 
 ``` ruby
 gem "ferrum"
 ```
 
+
+## Examples
+
 Navigate to a website and save a screenshot:
 
 ```ruby
 browser = Ferrum::Browser.new
-browser.goto("https://google.com")
+browser.go_to("https://google.com")
 browser.screenshot(path: "google.png")
 browser.quit
 ```
@@ -46,10 +86,10 @@ Interact with a page:
 
 ```ruby
 browser = Ferrum::Browser.new
-browser.goto("https://google.com")
-input = browser.at_xpath("//div[@id='searchform']/form//input[@type='text']")
-input.focus.type("Ruby headless driver for Capybara", :Enter)
-browser.at_css("a > h3").text # => "machinio/cuprite: Headless Chrome driver for Capybara - GitHub"
+browser.go_to("https://google.com")
+input = browser.at_xpath("//input[@name='q']")
+input.focus.type("Ruby headless driver for Chrome", :Enter)
+browser.at_css("a > h3").text # => "rubycdp/ferrum: Ruby Chrome/Chromium driver - GitHub"
 browser.quit
 ```
 
@@ -57,7 +97,7 @@ Evaluate some JavaScript and get full width/height:
 
 ```ruby
 browser = Ferrum::Browser.new
-browser.goto("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
+browser.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
 width, height = browser.evaluate <<~JS
   [document.documentElement.offsetWidth,
    document.documentElement.offsetHeight]
@@ -71,7 +111,7 @@ Do any mouse movements you like:
 ```ruby
 # Trace a 100x100 square
 browser = Ferrum::Browser.new
-browser.goto("https://google.com")
+browser.go_to("https://google.com")
 browser.mouse
   .move(x: 0, y: 0)
   .down
@@ -84,7 +124,17 @@ browser.mouse
 browser.quit
 ```
 
-## Customization ##
+
+## Docker
+
+In docker as root you must pass the no-sandbox browser option:
+
+```ruby
+Ferrum::Browser.new(browser_options: { 'no-sandbox': nil })
+```
+
+
+## Customization
 
 You can customize options with the following code in your test setup:
 
@@ -93,36 +143,48 @@ Ferrum::Browser.new(options)
 ```
 
 * options `Hash`
-  * `:browser_path` (String) - Path to chrome binary, you can also set ENV
-      variable as `BROWSER_PATH=some/path/chrome bundle exec rspec`.
   * `:headless` (Boolean) - Set browser as headless or not, `true` by default.
-  * `:slowmo` (Integer | Float) - Set a delay to wait before sending command.
-      Usefull companion of headless option, so that you have time to see changes.
+  * `:xvfb` (Boolean) - Run browser in a virtual framebuffer, `false` by default.
+  * `:window_size` (Array) - The dimensions of the browser window in which to
+      test, expressed as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
+  * `:extensions` (Array[String | Hash]) - An array of paths to files or JS
+      source code to be preloaded into the browser e.g.:
+      `["/path/to/script.js", { source: "window.secret = 'top'" }]`
   * `:logger` (Object responding to `puts`) - When present, debug output is
       written to this object.
+  * `:slowmo` (Integer | Float) - Set a delay in seconds to wait before sending command.
+      Usefull 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.
   * `:js_errors` (Boolean) - When true, JavaScript errors get re-raised in Ruby.
-  * `:window_size` (Array) - The dimensions of the browser window in which to
-      test, expressed as a 2-element array, e.g. [1024, 768]. Default: [1024, 768]
+  * `:pending_connection_errors` (Boolean) - When main frame is still waiting for slow responses while timeout is
+      reached `PendingConnectionsError` is raised. It's better to figure out why you have slow responses and fix or
+      block them rather than turn this setting off. Default is true.
+  * `:browser_name` (Symbol) - `:chrome` by default, only experimental support
+      for `:firefox` for now.
+  * `:browser_path` (String) - Path to Chrome binary, you can also set ENV
+      variable as `BROWSER_PATH=some/path/chrome bundle exec rspec`.
   * `:browser_options` (Hash) - Additional command line options,
       [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
       e.g. `{ "ignore-certificate-errors" => nil }`
-  * `:extensions` (Array) - An array of JS files to be preloaded into the browser
+  * `:ignore_default_browser_options` (Boolean) - Ferrum has a number of default
+      options it passes to the browser, if you set this to `true` then only
+      options you put in `:browser_options` will be passed to the browser,
+      except required ones of course.
   * `:port` (Integer) - Remote debugging port for headless Chrome
   * `:host` (String) - Remote debugging address for headless Chrome
   * `:url` (String) - URL for a running instance of Chrome. If this is set, a
       browser process will not be spawned.
   * `:process_timeout` (Integer) - How long to wait for the Chrome process to
       respond on startup
-
-
-#### The API below is for master branch and a subject to change before 1.0
+  * `:ws_max_receive_size` (Integer) - How big messages to accept from Chrome
+      over the web socket, in bytes. Defaults to 64MB. Incoming messages larger
+      than this will cause a `Ferrum::DeadBrowserError`.
 
 
 ## Navigation
 
-#### goto(url) : `String`
+#### go_to(url) : `String`
 
 Navigate page to.
 
@@ -130,7 +192,7 @@ Navigate page to.
   configuring driver.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 ```
 
 #### back
@@ -138,7 +200,7 @@ browser.goto("https://github.com/")
 Navigate to the previous page in history.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.at_xpath("//a").click
 browser.back
 ```
@@ -148,7 +210,7 @@ browser.back
 Navigate to the next page in history.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.at_xpath("//a").click
 browser.back
 browser.forward
@@ -159,10 +221,19 @@ browser.forward
 Reload current page.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.refresh
 ```
 
+#### stop
+
+Stop all navigations and loading pending resources on the page
+
+```ruby
+browser.go_to("https://github.com/")
+browser.stop
+```
+
 
 ## Finders
 
@@ -176,7 +247,7 @@ provided node.
     * :within `Node` | `nil`
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.at_css("a[aria-label='Issues you created']") # => Node
 ```
 
@@ -191,7 +262,7 @@ document or provided node.
   * :within `Node` | `nil`
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.css("a[aria-label='Issues you created']") # => [Node]
 ```
 
@@ -204,7 +275,7 @@ Find node by xpath.
   * :within `Node` | `nil`
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.at_xpath("//a[@aria-label='Issues you created']") # => Node
 ```
 
@@ -217,7 +288,7 @@ Find nodes by xpath.
   * :within `Node` | `nil`
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.xpath("//a[@aria-label='Issues you created']") # => [Node]
 ```
 
@@ -226,7 +297,7 @@ browser.xpath("//a[@aria-label='Issues you created']") # => [Node]
 Returns current top window location href.
 
 ```ruby
-browser.goto("https://google.com/")
+browser.go_to("https://google.com/")
 browser.current_url # => "https://www.google.com/"
 ```
 
@@ -235,7 +306,7 @@ browser.current_url # => "https://www.google.com/"
 Returns current top window title
 
 ```ruby
-browser.goto("https://google.com/")
+browser.go_to("https://google.com/")
 browser.current_title # => "Google"
 ```
 
@@ -244,7 +315,7 @@ browser.current_title # => "Google"
 Returns current page's html.
 
 ```ruby
-browser.goto("https://google.com/")
+browser.go_to("https://google.com/")
 browser.body # => '<html itemscope="" itemtype="http://schema.org/WebPage" lang="ru"><head>...
 ```
 
@@ -265,18 +336,21 @@ Saves screenshot on a disk or returns it as base64.
   * :full `Boolean` whether you need full page screenshot or a viewport
   * :selector `String` css selector for given element
   * :scale `Float` zoom in/out
+  * :background_color `Ferrum::RGBA.new(0, 0, 0, 0.0)` to have specific background color
 
 ```ruby
-browser.goto("https://google.com/")
+browser.go_to("https://google.com/")
 # Save on the disk in PNG
 browser.screenshot(path: "google.png") # => 134660
 # Save on the disk in JPG
 browser.screenshot(path: "google.jpg") # => 30902
 # Save to Base64 the whole page not only viewport and reduce quality
 browser.screenshot(full: true, quality: 60) # "iVBORw0KGgoAAAANSUhEUgAABAAAAAMACAYAAAC6uhUNAAAAAXNSR0IArs4c6Q...
+# Save with specific background color
+browser.screenshot(background_color: Ferrum::RGBA.new(0, 0, 0, 0.0))
 ```
 
-#### pdf(\*\*options) : `String` | `Integer`
+#### pdf(\*\*options) : `String` | `Boolean`
 
 Saves PDF on a disk or returns it as base64.
 
@@ -294,9 +368,21 @@ Saves PDF on a disk or returns it as base64.
   * See other [native options](https://chromedevtools.github.io/devtools-protocol/tot/Page#method-printToPDF) you can pass
 
 ```ruby
-browser.goto("https://google.com/")
+browser.go_to("https://google.com/")
 # Save to disk as a PDF
-browser.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => 14983
+browser.pdf(path: "google.pdf", paper_width: 1.0, paper_height: 1.0) # => true
+```
+
+#### mhtml(\*\*options) : `String` | `Integer`
+
+Saves MHTML on a disk or returns it as a string.
+
+* options `Hash`
+  * :path `String` to save a file on the disk.
+
+```ruby
+browser.go_to("https://google.com/")
+browser.mhtml(path: "google.mhtml") # => 87742
 ```
 
 
@@ -310,7 +396,7 @@ Returns all information about network traffic as `Network::Exchange` instance
 which in general is a wrapper around `request`, `response` and `error`.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.network.traffic # => [#<Ferrum::Network::Exchange, ...]
 ```
 
@@ -319,7 +405,7 @@ browser.network.traffic # => [#<Ferrum::Network::Exchange, ...]
 Page request of the main frame.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.network.request # => #<Ferrum::Network::Request...
 ```
 
@@ -328,7 +414,7 @@ browser.network.request # => #<Ferrum::Network::Request...
 Page response of the main frame.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.network.response # => #<Ferrum::Network::Response...
 ```
 
@@ -338,10 +424,28 @@ Contains the status code of the main page response (e.g., 200 for a
 success). This is just a shortcut for `response.status`.
 
 ```ruby
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 browser.network.status # => 200
 ```
 
+#### wait_for_idle(\*\*options)
+
+Waits for network idle or raises `Ferrum::TimeoutError` error
+
+* options `Hash`
+  * :connections `Integer` how many connections are allowed for network to be
+    idling, `0` by default
+  * :duration `Float` sleep for given amount of time and check again, `0.05` by
+    default
+  * :timeout `Float` during what time we try to check idle, `browser.timeout`
+    by default
+
+```ruby
+browser.go_to("https://example.com/")
+browser.at_xpath("//a[text() = 'No UI changes button']").click
+browser.network.wait_for_idle
+```
+
 #### clear(type)
 
 Clear browser's cache or collected traffic.
@@ -350,7 +454,7 @@ Clear browser's cache or collected traffic.
 
 ```ruby
 traffic = browser.network.traffic # => []
-browser.goto("https://github.com/")
+browser.go_to("https://github.com/")
 traffic.size # => 51
 browser.network.clear(:traffic)
 traffic.size # => 0
@@ -378,25 +482,52 @@ browser.on(:request) do |request|
     request.continue
   end
 end
-browser.goto("https://google.com")
+browser.go_to("https://google.com")
 ```
 
-#### authorize(\*\*options)
+#### authorize(\*\*options, &block)
 
-If site uses authorization you can provide credentials using this method.
+If site or proxy uses authorization you can provide credentials using this method.
 
 * options `Hash`
   * :type `Symbol` `:server` | `:proxy` site or proxy authorization
   * :user `String`
   * :password `String`
+* &block accepts authenticated request, which you must subsequently allow or deny, if you don't
+care about unwanted requests just call `request.continue`.
 
 ```ruby
-browser.network.authorize(user: "login", password: "pass")
-browser.goto("http://example.com/authenticated")
+browser.network.authorize(user: "login", password: "pass") { |req| req.continue }
+browser.go_to("http://example.com/authenticated")
 puts browser.network.status # => 200
 puts browser.body # => Welcome, authenticated client
 ```
 
+Since Chrome implements authorize using request interception you must continue or abort authorized requests. If you
+already have code that uses interception you can use `authorize` without block, but if not you are obliged to pass
+block, so this is version doesn't pass block and can work just fine:
+
+```ruby
+browser = Ferrum::Browser.new
+browser.network.intercept
+browser.on(:request) do |request|
+  if request.resource_type == "Image"
+    request.abort
+  else
+    request.continue
+  end
+end
+
+browser.network.authorize(user: "login", password: "pass", type: :proxy)
+
+browser.go_to("https://google.com")
+
+```
+
+You used to call `authorize` method without block, but since it's implemented using request interception there could be
+a collision with another part of your code that also uses request interception, so that authorize allows the request
+while your code denies but it's too late. The block is mandatory now.
+
 
 ### Mouse
 
@@ -412,7 +543,7 @@ Scroll page to a given x, y
   displayed in the upper left
 
 ```ruby
-browser.goto("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
+browser.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
 browser.mouse.scroll_to(0, 400)
 ```
 
@@ -517,6 +648,8 @@ Sets given values as cookie
   * :value `String`
   * :domain `String`
   * :expires `Integer`
+  * :samesite `String`
+  * :httponly `Boolean`
 
 ```ruby
 browser.cookies.set(name: "stealth", value: "omg", domain: "google.com") # => true
@@ -628,22 +761,163 @@ browser.add_script_tag(url: "http://example.com/stylesheet.css") # => true
 
 ```ruby
 browser.add_style_tag(content: "h1 { font-size: 40px; }") # => true
+
+```
+#### bypass_csp(enabled) : `Boolean`
+
+* enabled `Boolean`, `true` by default
+
+```ruby
+browser.bypass_csp # => true
+browser.go_to("https://github.com/ruby-concurrency/concurrent-ruby/blob/master/docs-source/promises.in.md")
+browser.refresh
+browser.add_script_tag(content: "window.__injected = 42")
+browser.evaluate("window.__injected") # => 42
 ```
 
 
 ## Frames
 
-#### frames
-#### main_frame
-#### frame_by
+#### frames : `Array[Frame] | []`
 
-Play around inside given frame
+Returns all the frames current page have.
 
 ```ruby
-browser.goto("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+browser.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>,
+#   ...
+# ]
+```
+
+#### main_frame : `Frame`
+
+Returns page's main frame, the top of the tree and the parent of all frames.
+
+#### frame_by(\*\*options) : `Frame | nil`
+
+Find frame by given options.
+
+* options `Hash`
+  * :id `String` - Unique frame's id that browser provides
+  * :name `String` - Frame's name if there's one
+
+```ruby
+browser.frame_by(id: "C6D104CE454A025FBCF22B98DE612B12")
+```
+
+
+## Frame
+
+#### id : `String`
+
+Frame's unique id.
+
+#### parent_id : `String | nil`
+
+Parent frame id if this one is nested in another one.
+
+#### execution_id : `Integer`
+
+Execution context id which is used by JS, each frame has it's own context in
+which JS evaluates.
+
+#### name : `String | nil`
+
+If frame was given a name it should be here.
+
+#### state : `Symbol | nil`
+
+One of the states frame's in:
+
+* `:started_loading`
+* `:navigated`
+* `:stopped_loading`
+
+#### url : `String`
+
+Returns current frame's location href.
+
+```ruby
+browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+frame = browser.frames[1]
+frame.url # => https://interactive-examples.mdn.mozilla.net/pages/tabbed/iframe.html
+```
+
+#### title
+
+Returns current frame's title.
+
+```ruby
+browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
+frame = browser.frames[1]
+frame.title # => HTML Demo: <iframe>
+```
+
+#### main? : `Boolean`
+
+If current frame is the main frame of the page (top of the tree).
+
+```ruby
+browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+frame = browser.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
+frame.main? # => false
+```
+
+#### current_url : `String`
+
+Returns current frame's top window location href.
+
+```ruby
+browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+frame = browser.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
+frame.current_url # => "https://www.w3schools.com/tags/tag_frame.asp"
+```
+
+#### current_title : `String`
+
+Returns current frame's top window title.
+
+```ruby
+browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+frame = browser.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
+frame.current_title # => "HTML frame tag"
+```
+
+#### body : `String`
+
+Returns current frame's html.
+
+```ruby
+browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+frame = browser.frame_by(id: "C09C4E4404314AAEAE85928EAC109A93")
+frame.body # => "<html><head></head><body></body></html>"
+```
+
+#### doctype
+
+Returns current frame's doctype.
+
+```ruby
+browser.go_to("https://www.w3schools.com/tags/tag_frame.asp")
+browser.main_frame.doctype # => "<!DOCTYPE html>"
+```
+
+#### set_content(html)
+
+Sets a content of a given frame.
+
+  * html `String`
+
+```ruby
+browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
 frame = browser.frames[1]
-puts frame.title # => HTML Demo: <iframe>
-puts frame.url # => https://interactive-examples.mdn.mozilla.net/pages/tabbed/iframe.html
+frame.body # <html lang="en"><head><style>body {transition: opacity ease-in 0.2s; }...
+frame.set_content("<html><head></head><body><p>lol</p></body></html>")
+frame.body # => <html><head></head><body><p>lol</p></body></html>
 ```
 
 
@@ -668,7 +942,7 @@ browser.on(:dialog) do |dialog|
     dialog.dismiss
   end
 end
-browser.goto("https://google.com")
+browser.go_to("https://google.com")
 ```
 
 
@@ -685,13 +959,13 @@ context = browser.contexts.create
 
 t1 = Thread.new(context) do |c|
   page = c.create_page
-  page.goto("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
+  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.goto("https://www.google.com/search?q=Ruby+static+typing")
+  page.go_to("https://www.google.com/search?q=Ruby+static+typing")
   page.screenshot(path: "t2.png")
 end
 
@@ -710,7 +984,7 @@ browser = Ferrum::Browser.new
 t1 = Thread.new(browser) do |b|
   context = b.contexts.create
   page = context.create_page
-  page.goto("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
+  page.go_to("https://www.google.com/search?q=Ruby+headless+driver+for+Capybara")
   page.screenshot(path: "t1.png")
   context.dispose
 end
@@ -718,7 +992,7 @@ end
 t2 = Thread.new(browser) do |b|
   context = b.contexts.create
   page = context.create_page
-  page.goto("https://www.google.com/search?q=Ruby+static+typing")
+  page.go_to("https://www.google.com/search?q=Ruby+static+typing")
   page.screenshot(path: "t2.png")
   context.dispose
 end
@@ -728,3 +1002,21 @@ t2.join
 
 browser.quit
 ```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/rubycdp/ferrum).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).