@@ -38,6 +38,92 @@ class Browser
3838 :proxy_server
3939 attr_writer :timeout
4040
41+ #
42+ # Initializes the browser.
43+ #
44+ # @param [Hash{Symbol => Object}, nil] options
45+ # Additional browser options.
46+ #
47+ # @option options [Boolean] :headless (true)
48+ # Set browser as headless or not.
49+ #
50+ # @option options [Boolean] :xvfb (false)
51+ # Run browser in a virtual framebuffer.
52+ #
53+ # @option options [(Integer, Integer)] :window_size ([1024, 768])
54+ # The dimensions of the browser window in which to test, expressed as a
55+ # 2-element array, e.g. `[1024, 768]`.
56+ #
57+ # @option options [Array<String, Hash>] :extensions
58+ # An array of paths to files or JS source code to be preloaded into the
59+ # browser e.g.: `["/path/to/script.js", { source: "window.secret = 'top'" }]`
60+ #
61+ # @option options [#puts] :logger
62+ # When present, debug output is written to this object.
63+ #
64+ # @option options [Integer, Float] :slowmo
65+ # Set a delay in seconds to wait before sending command.
66+ # Usefull companion of headless option, so that you have time to see
67+ # changes.
68+ #
69+ # @option options [Numeric] :timeout (5)
70+ # The number of seconds we'll wait for a response when communicating with
71+ # browser.
72+ #
73+ # @option options [Boolean] :js_errors
74+ # When true, JavaScript errors get re-raised in Ruby.
75+ #
76+ # @option options [Boolean] :pending_connection_errors (true)
77+ # When main frame is still waiting for slow responses while timeout is
78+ # reached {PendingConnectionsError} is raised. It's better to figure out
79+ # why you have slow responses and fix or block them rather than turn this
80+ # setting off.
81+ #
82+ # @option options [:chrome, :firefox] :browser_name (:chrome)
83+ # Sets the browser's name. **Note:** only experimental support for
84+ # `:firefox` for now.
85+ #
86+ # @option options [String] :browser_path
87+ # Path to Chrome binary, you can also set ENV variable as
88+ # `BROWSER_PATH=some/path/chrome bundle exec rspec`.
89+ #
90+ # @option options [Hash] :browser_options
91+ # Additional command line options, [see them all](https://peter.sh/experiments/chromium-command-line-switches/)
92+ # e.g. `{ "ignore-certificate-errors" => nil }`
93+ #
94+ # @option options [Boolean] :ignore_default_browser_options
95+ # Ferrum has a number of default options it passes to the browser,
96+ # if you set this to `true` then only options you put in
97+ # `:browser_options` will be passed to the browser, except required ones
98+ # of course.
99+ #
100+ # @option options [Integer] :port
101+ # Remote debugging port for headless Chrome.
102+ #
103+ # @option options [String] :host
104+ # Remote debugging address for headless Chrome.
105+ #
106+ # @option options [String] :url
107+ # URL for a running instance of Chrome. If this is set, a browser process
108+ # will not be spawned.
109+ #
110+ # @option options [Integer] :process_timeout
111+ # How long to wait for the Chrome process to respond on startup.
112+ #
113+ # @option options [Integer] :ws_max_receive_size
114+ # How big messages to accept from Chrome over the web socket, in bytes.
115+ # Defaults to 64MB. Incoming messages larger this will cause a
116+ # {Ferrum::DeadBrowserError}.
117+ #
118+ # @option options [Hash] :proxy
119+ # Specify proxy settings, [read more](https://github.com/rubycdp/ferrum#proxy).
120+ #
121+ # @option options [String] :save_path
122+ # Path to save attachments with [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header.
123+ #
124+ # @option options [Hash] :env
125+ # Environment variables you'd like to pass through to the process.
126+ #
41127 def initialize ( options = nil )
42128 options ||= { }
43129
@@ -80,6 +166,15 @@ def initialize(options = nil)
80166 start
81167 end
82168
169+ #
170+ # Sets the base URL.
171+ #
172+ # @param [String] value
173+ # The new base URL value.
174+ #
175+ # @return [String]
176+ # The base URL value.
177+ #
83178 def base_url = ( value )
84179 parsed = Addressable ::URI . parse ( value )
85180 unless BASE_URL_SCHEMA . include? ( parsed . normalized_scheme )
@@ -111,6 +206,19 @@ def extensions
111206 end
112207 end
113208
209+ #
210+ # Evaluate JavaScript to modify things before a page load.
211+ #
212+ # @param [String] expression
213+ # The JavaScript to add to each new document.
214+ #
215+ # @example
216+ # browser.evaluate_on_new_document <<~JS
217+ # Object.defineProperty(navigator, "languages", {
218+ # get: function() { return ["tlh"]; }
219+ # });
220+ # JS
221+ #
114222 def evaluate_on_new_document ( expression )
115223 extensions << expression
116224 end
@@ -126,6 +234,20 @@ def command(*args)
126234 raise
127235 end
128236
237+ #
238+ # Closes browser tabs opened by the `Browser` instance.
239+ #
240+ # @example
241+ # # connect to a long-running Chrome process
242+ # browser = Ferrum::Browser.new(url: 'http://localhost:9222')
243+ #
244+ # browser.go_to("https://github.com/")
245+ #
246+ # # clean up, lest the tab stays there hanging forever
247+ # browser.reset
248+ #
249+ # browser.quit
250+ #
129251 def reset
130252 @window_size = @original_window_size
131253 contexts . reset
@@ -151,6 +273,13 @@ def crash
151273 command ( "Browser.crash" )
152274 end
153275
276+ #
277+ # Gets the version information from the browser.
278+ #
279+ # @return [VersionInfo]
280+ #
281+ # @since 0.13
282+ #
154283 def version
155284 VersionInfo . new ( command ( "Browser.getVersion" ) )
156285 end
0 commit comments