ferrum 0.18.0 → 0.19.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -116,7 +116,8 @@ module Ferrum
116
116
  # Returns the element in which the window is embedded.
117
117
  #
118
118
  # @return [Node, nil]
119
- # The element in which the window is embedded.
119
+ # The element in which the window is embedded, `nil` for the main frame
120
+ # and for a frame from a different origin than its parent.
120
121
  #
121
122
  # @example
122
123
  # browser.go_to("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe")
@@ -243,6 +244,54 @@ module Ferrum
243
244
  evaluate_func(expr, selector, within)
244
245
  end
245
246
 
247
+ #
248
+ # Finds a node by using a CSS path or XPath selector, retrying until
249
+ # it appears or `timeout` elapses. Pass exactly one of `css`/`xpath`;
250
+ # each attempt delegates to {#at_css}/{#at_xpath} respectively, so it
251
+ # matches their behavior exactly.
252
+ #
253
+ # @param [String, nil] css
254
+ # The CSS path selector. Mutually exclusive with `xpath`.
255
+ #
256
+ # @param [String, nil] xpath
257
+ # The XPath selector. Mutually exclusive with `css`.
258
+ #
259
+ # @param [Node, nil] within
260
+ # The parent node to search within.
261
+ #
262
+ # @param [Float, Integer] timeout
263
+ # How long to keep retrying, in seconds.
264
+ #
265
+ # @param [Float, Integer] interval
266
+ # How long to sleep between attempts, in seconds.
267
+ #
268
+ # @return [Node, nil]
269
+ # The matching node, or `nil` if `timeout` elapses without a match.
270
+ #
271
+ # @raise [ArgumentError]
272
+ # If neither or both of `css`/`xpath` are given.
273
+ #
274
+ # @example
275
+ # browser.go_to("https://github.com/")
276
+ # browser.wait_for_selector(css: "a[aria-label='Issues you created']") # => Node
277
+ #
278
+ def wait_for_selector(css: nil, xpath: nil, within: nil, timeout: @page.timeout, interval: 0.05)
279
+ raise ArgumentError, "pass either `css:` or `xpath:`" if css && xpath
280
+
281
+ selector, method_name = css ? [css, :at_css] : [xpath, :at_xpath]
282
+ raise ArgumentError, "pass either `css:` or `xpath:`" unless selector
283
+
284
+ start = Utils::ElapsedTime.monotonic_time
285
+
286
+ until (node = send(method_name, selector, within: within))
287
+ return nil if Utils::ElapsedTime.timeout?(start, timeout)
288
+
289
+ sleep(interval)
290
+ end
291
+
292
+ node
293
+ end
294
+
246
295
  #
247
296
  # Adds a `<script>` tag to the document.
248
297
  #
@@ -146,7 +146,8 @@ module Ferrum
146
146
  private
147
147
 
148
148
  def call(expression:, arguments: [], on: nil, wait: 0, handle: true, **options)
149
- errors = [NodeNotFoundError, NoExecutionContextError]
149
+ # do not rescue -> retry if we operate on an existing node
150
+ errors = on ? [] : [NodeNotFoundError, NoExecutionContextError]
150
151
 
151
152
  Utils::Attempt.with_retry(errors: errors, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP) do
152
153
  params = options.dup
@@ -185,7 +186,7 @@ module Ferrum
185
186
  end
186
187
  end
187
188
 
188
- def handle_response(response)
189
+ def handle_response(response, check_cyclic: true)
189
190
  case response["type"]
190
191
  when "boolean", "number", "string"
191
192
  response["value"]
@@ -201,10 +202,10 @@ module Ferrum
201
202
  description = @page.command("DOM.describeNode", objectId: object_id)["node"]
202
203
  Node.new(self, @page.target_id, description, object_id: object_id)
203
204
  when "array"
204
- reduce_props(object_id, []) do |memo, key, value|
205
+ reduce_props(object_id, [], check_cyclic: check_cyclic) do |memo, key, value|
205
206
  next(memo) unless Integer(key, exception: false)
206
207
 
207
- value = value["objectId"] ? handle_response(value) : value["value"]
208
+ value = value["objectId"] ? handle_response(value, check_cyclic: false) : value["value"]
208
209
  memo.insert(key.to_i, value)
209
210
  end.compact
210
211
  when "date"
@@ -212,8 +213,8 @@ module Ferrum
212
213
  when "null"
213
214
  nil
214
215
  else
215
- reduce_props(object_id, {}) do |memo, key, value|
216
- value = value["objectId"] ? handle_response(value) : value["value"]
216
+ reduce_props(object_id, {}, check_cyclic: check_cyclic) do |memo, key, value|
217
+ value = value["objectId"] ? handle_response(value, check_cyclic: false) : value["value"]
217
218
  memo.merge(key => value)
218
219
  end
219
220
  end
@@ -233,8 +234,8 @@ module Ferrum
233
234
  end
234
235
  end
235
236
 
236
- def reduce_props(object_id, to)
237
- if cyclic?(object_id).dig("result", "value")
237
+ def reduce_props(object_id, to, check_cyclic: true)
238
+ if check_cyclic && cyclic?(object_id).dig("result", "value")
238
239
  to.is_a?(Array) ? [cyclic_object] : cyclic_object
239
240
  else
240
241
  props = @page.command("Runtime.getProperties", ownProperties: true, objectId: object_id)
@@ -2,14 +2,28 @@
2
2
 
3
3
  module Ferrum
4
4
  # Shared by {Page} and {Worker}: subscribes to the CDP events behind the
5
- # `:request` (Fetch-domain request interception) and `:auth` (proxy/basic
6
- # auth challenges) pseudo-events, on top of the includer's own `client`
7
- # and `network`. Anything else is passed straight through to `client`.
5
+ # `:request` (Fetch-domain request interception), `:response` (a request's
6
+ # response has fully loaded) and `:auth` (proxy/basic auth challenges)
7
+ # pseudo-events, on top of the includer's own `client` and `network`.
8
+ # Anything else is passed straight through to `client`.
8
9
  module Interceptable
9
- # Subscribes to a CDP event, or to `:request`/`:auth`.
10
+ # Subscribes to a CDP event, or to `:request`/`:response`/`:auth`.
10
11
  #
11
12
  # @param [Symbol, String] name
12
13
  #
14
+ # @yieldparam [Network::InterceptedRequest, Network::Exchange, Network::AuthRequest, Hash] arg
15
+ # For `:request`, the intercepted {Network::InterceptedRequest}. For
16
+ # `:response`, the finished {Network::Exchange}. For `:auth`, the
17
+ # {Network::AuthRequest} challenge. For any other (raw CDP) event name,
18
+ # the event's params `Hash`.
19
+ #
20
+ # @yieldparam [Integer] index
21
+ # This callback's position among all callbacks currently registered for
22
+ # the event.
23
+ #
24
+ # @yieldparam [Integer] total
25
+ # Total number of callbacks currently registered for the event.
26
+ #
13
27
  # @return [Integer]
14
28
  # The subscription id, used to unsubscribe via {#off}.
15
29
  def on(name, &block)
@@ -21,6 +35,11 @@ module Ferrum
21
35
  exchange.intercepted_request = request
22
36
  block.call(request, index, total)
23
37
  end
38
+ when :response
39
+ client.on("Network.loadingFinished") do |params, index, total|
40
+ exchange = network.select(params["requestId"]).last
41
+ block.call(exchange, index, total) if exchange
42
+ end
24
43
  when :auth
25
44
  client.on("Fetch.authRequired") do |params, index, total|
26
45
  request = Network::AuthRequest.new(self, params)
@@ -43,6 +62,8 @@ module Ferrum
43
62
  case name
44
63
  when :request
45
64
  client.off("Fetch.requestPaused", id)
65
+ when :response
66
+ client.off("Network.loadingFinished", id)
46
67
  when :auth
47
68
  client.off("Fetch.authRequired", id)
48
69
  else
data/lib/ferrum/mouse.rb CHANGED
@@ -152,6 +152,7 @@ module Ferrum
152
152
  from_y = @y
153
153
  @x = x
154
154
  @y = y
155
+ button = pressed_button
155
156
 
156
157
  steps.times do |i|
157
158
  new_x = from_x + ((@x - from_x) * ((i + 1) / steps.to_f))
@@ -162,6 +163,7 @@ module Ferrum
162
163
  type: "mouseMoved",
163
164
  x: new_x,
164
165
  y: new_y,
166
+ button: button,
165
167
  buttons: @buttons)
166
168
  end
167
169
 
@@ -185,6 +187,10 @@ module Ferrum
185
187
  button
186
188
  end
187
189
 
190
+ def pressed_button
191
+ BUTTON_MASKS.find { |_name, mask| mask.positive? && @buttons.anybits?(mask) }&.first || "none"
192
+ end
193
+
188
194
  def register_event_button(type, button)
189
195
  case type
190
196
  when "mousePressed"
@@ -32,9 +32,9 @@ module Ferrum
32
32
  A1: { width: 23.40, height: 33.10 },
33
33
  A2: { width: 16.54, height: 23.40 },
34
34
  A3: { width: 11.70, height: 16.54 },
35
- A4: { width: 8.27, height: 11.70 },
36
- A5: { width: 5.83, height: 8.27 },
37
- A6: { width: 4.13, height: 5.83 }
35
+ A4: { width: 8.27, height: 11.70 },
36
+ A5: { width: 5.83, height: 8.27 },
37
+ A6: { width: 4.13, height: 5.83 }
38
38
  }.freeze
39
39
 
40
40
  #
@@ -70,7 +70,8 @@ module Ferrum
70
70
 
71
71
  #
72
72
  # Reads a CDP `IO` stream in chunks, writing each chunk to the given
73
- # output until the stream is exhausted.
73
+ # output until the stream is exhausted, then releases the stream
74
+ # handle on the browser side.
74
75
  #
75
76
  # @param [#<<] output
76
77
  # Anything that responds to `#<<`, e.g. an open `File` or a `String`.
@@ -88,6 +89,20 @@ module Ferrum
88
89
  output << chunk
89
90
  break if result["eof"]
90
91
  end
92
+ close_stream(handle: handle)
93
+ end
94
+
95
+ #
96
+ # Releases a CDP `IO` stream handle, discarding any backing storage
97
+ # the browser is holding for it.
98
+ #
99
+ # @param [String] handle
100
+ # The CDP `IO` stream handle to close.
101
+ #
102
+ # @return [void]
103
+ #
104
+ def close_stream(handle:)
105
+ command("IO.close", handle: handle)
91
106
  end
92
107
  end
93
108
  end
data/lib/ferrum/page.rb CHANGED
@@ -31,7 +31,7 @@ module Ferrum
31
31
 
32
32
  extend Forwardable
33
33
 
34
- delegate %i[at_css at_xpath css xpath
34
+ delegate %i[at_css at_xpath css xpath wait_for_selector
35
35
  current_url current_title url title body doctype content=
36
36
  execution_id execution_id! evaluate evaluate_on evaluate_async execute evaluate_func
37
37
  add_script_tag add_style_tag] => :main_frame
@@ -176,9 +176,15 @@ module Ferrum
176
176
  #
177
177
  # @param [Float] scale_factor device scale factor value. 0 disables the override
178
178
  #
179
- # @param [Boolean] mobile whether to emulate mobile device
179
+ # @param [Boolean] mobile whether to emulate mobile device and enable touch
180
180
  #
181
- def set_viewport(width:, height:, scale_factor: 0, mobile: false)
181
+ def set_viewport(width: 0, height: 0, scale_factor: 0, mobile: false)
182
+ command(
183
+ "Emulation.setTouchEmulationEnabled",
184
+ enabled: mobile,
185
+ maxTouchPoints: 1
186
+ )
187
+
182
188
  command(
183
189
  "Emulation.setDeviceMetricsOverride",
184
190
  slowmoable: true,
@@ -454,8 +460,8 @@ module Ferrum
454
460
  result
455
461
  end
456
462
 
457
- # Subscribes to a CDP event, or to `:dialog`, `:request`, `:auth` (the
458
- # latter two handled by {Interceptable}).
463
+ # Subscribes to a CDP event, or to `:dialog`, `:request`, `:response`,
464
+ # `:auth` (the latter three handled by {Interceptable}).
459
465
  #
460
466
  # @param [Symbol, String] name
461
467
  #
data/lib/ferrum/target.rb CHANGED
@@ -17,11 +17,12 @@ module Ferrum
17
17
  attr_reader :options
18
18
  attr_accessor :session_id
19
19
 
20
- def initialize(browser_client, session_id = nil, params = nil)
20
+ def initialize(browser_client, session_id = nil, params = nil, implicit: false)
21
21
  @page = nil
22
22
  @worker = nil
23
23
  @session_id = session_id
24
24
  @params = params
25
+ @implicit = implicit
25
26
  @browser_client = browser_client
26
27
  @options = browser_client.options
27
28
  end
@@ -137,11 +138,14 @@ module Ferrum
137
138
  @params["parentId"]
138
139
  end
139
140
 
140
- # The id of the browser context this target belongs to.
141
+ # The id of the browser context this target belongs to, `nil` for the
142
+ # browser's implicit context, which Chrome doesn't let us address by id,
143
+ # see {Context#implicit?}. Commands scoped to a browser context target it
144
+ # by omitting `browserContextId`.
141
145
  #
142
146
  # @return [String, nil]
143
147
  def context_id
144
- @params["browserContextId"]
148
+ @params["browserContextId"] unless @implicit
145
149
  end
146
150
 
147
151
  # Whether this target is a window/tab, i.e. was opened via
@@ -14,10 +14,12 @@ module Ferrum
14
14
  #
15
15
  # @param [Boolean] abort_on_exception
16
16
  # Whether the thread aborts the process if it raises an unhandled exception.
17
+ # Off by default: an exception in one of Ferrum's own threads reaches the
18
+ # main thread wherever it happens to be, or kills the process outright.
17
19
  #
18
20
  # @return [Thread]
19
21
  #
20
- def spawn(abort_on_exception: true)
22
+ def spawn(abort_on_exception: false)
21
23
  ::Thread.new(abort_on_exception) do |whether_abort_on_exception|
22
24
  ::Thread.current.abort_on_exception = whether_abort_on_exception
23
25
  ::Thread.current.report_on_exception = true if ::Thread.current.respond_to?(:report_on_exception=)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Ferrum
4
- VERSION = "0.18.0"
4
+ VERSION = "0.19.2"
5
5
  end
data/lib/ferrum.rb CHANGED
@@ -11,7 +11,7 @@ require "ferrum/browser"
11
11
  require "ferrum/node"
12
12
 
13
13
  #
14
- # Ferrum is a pure Ruby driver for headless Chrome and Firefox. It talks
14
+ # Ferrum is a pure Ruby driver for headless Chrome. It talks
15
15
  # directly to the browser over the Chrome DevTools Protocol (CDP), so it
16
16
  # doesn't depend on Selenium, WebDriver or any other third party gem.
17
17
  #
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ferrum
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.18.0
4
+ version: 0.19.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Dmitry Vorotilin
@@ -83,8 +83,8 @@ files:
83
83
  - lib/ferrum/browser/options.rb
84
84
  - lib/ferrum/browser/options/base.rb
85
85
  - lib/ferrum/browser/options/chrome.rb
86
- - lib/ferrum/browser/options/firefox.rb
87
86
  - lib/ferrum/browser/process.rb
87
+ - lib/ferrum/browser/process/killer.rb
88
88
  - lib/ferrum/browser/version_info.rb
89
89
  - lib/ferrum/browser/xvfb.rb
90
90
  - lib/ferrum/client.rb
@@ -155,7 +155,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
155
155
  - !ruby/object:Gem::Version
156
156
  version: '0'
157
157
  requirements: []
158
- rubygems_version: 4.0.16
158
+ rubygems_version: 4.0.6
159
159
  specification_version: 4
160
160
  summary: Ruby headless Chrome driver
161
161
  test_files: []
@@ -1,70 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Ferrum
4
- class Browser
5
- class Options
6
- #
7
- # Firefox-specific default flags and binary locations. Provides the CLI
8
- # flags required to drive Firefox over CDP (remote debugger address and
9
- # profile directory) along with its (minimal) set of default flags.
10
- #
11
- class Firefox < Base
12
- DEFAULT_OPTIONS = {
13
- "headless" => nil
14
- }.freeze
15
-
16
- MAC_BIN_PATH = [
17
- "/Applications/Firefox.app/Contents/MacOS/firefox-bin"
18
- ].freeze
19
- LINUX_BIN_PATH = %w[firefox].freeze
20
- WINDOWS_BIN_PATH = [
21
- "C:/Program Files/Firefox Developer Edition/firefox.exe",
22
- "C:/Program Files/Mozilla Firefox/firefox.exe"
23
- ].freeze
24
- PLATFORM_PATH = {
25
- mac: MAC_BIN_PATH,
26
- windows: WINDOWS_BIN_PATH,
27
- linux: LINUX_BIN_PATH
28
- }.freeze
29
-
30
- #
31
- # Merges CLI flags required for Firefox to work with CDP.
32
- #
33
- # @param [Hash] flags
34
- # Flags to merge required ones into.
35
- #
36
- # @param [Ferrum::Browser::Options] options
37
- # Browser options.
38
- #
39
- # @param [String] user_data_dir
40
- # Path to the browser's profile directory.
41
- #
42
- # @return [Hash]
43
- # Merged flags.
44
- #
45
- def merge_required(flags, options, user_data_dir)
46
- flags.merge("remote-debugger" => "#{options.host}:#{options.port}", "profile" => user_data_dir)
47
- end
48
-
49
- #
50
- # Merges Firefox's default flags with the given ones.
51
- #
52
- # @param [Hash] flags
53
- # Flags that take precedence over the defaults.
54
- #
55
- # @param [Ferrum::Browser::Options] options
56
- # Browser options.
57
- #
58
- # @return [Hash]
59
- # Merged flags.
60
- #
61
- def merge_default(flags, options)
62
- defaults = except("headless") unless options.headless
63
-
64
- defaults ||= DEFAULT_OPTIONS
65
- defaults.merge(flags)
66
- end
67
- end
68
- end
69
- end
70
- end