ferrum 0.19.2 → 0.20.1

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.
Files changed (41) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +60 -0
  3. data/lib/ferrum/browser/binary.rb +1 -2
  4. data/lib/ferrum/browser/options.rb +33 -12
  5. data/lib/ferrum/browser/process/output.rb +143 -0
  6. data/lib/ferrum/browser/process.rb +42 -69
  7. data/lib/ferrum/browser.rb +9 -23
  8. data/lib/ferrum/client/web_socket.rb +4 -15
  9. data/lib/ferrum/client.rb +1 -1
  10. data/lib/ferrum/console/location.rb +42 -0
  11. data/lib/ferrum/console/message.rb +230 -0
  12. data/lib/ferrum/console.rb +157 -0
  13. data/lib/ferrum/context.rb +23 -15
  14. data/lib/ferrum/contexts.rb +41 -18
  15. data/lib/ferrum/errors.rb +7 -5
  16. data/lib/ferrum/frame/dom.rb +50 -44
  17. data/lib/ferrum/frame/runtime/legacy.rb +336 -0
  18. data/lib/ferrum/frame/runtime.rb +416 -186
  19. data/lib/ferrum/frame/script.rb +289 -0
  20. data/lib/ferrum/frame.rb +33 -4
  21. data/lib/ferrum/interceptable.rb +19 -9
  22. data/lib/ferrum/isolated_world.rb +94 -0
  23. data/lib/ferrum/keyboard.rb +95 -8
  24. data/lib/ferrum/log/annotated.rb +77 -0
  25. data/lib/ferrum/log/default.rb +55 -0
  26. data/lib/ferrum/log/json.rb +32 -0
  27. data/lib/ferrum/log/paint.rb +28 -0
  28. data/lib/ferrum/log.rb +247 -0
  29. data/lib/ferrum/mouse.rb +16 -8
  30. data/lib/ferrum/node.rb +127 -52
  31. data/lib/ferrum/page/frames.rb +11 -3
  32. data/lib/ferrum/page/screenshot.rb +8 -7
  33. data/lib/ferrum/page.rb +112 -61
  34. data/lib/ferrum/proxy.rb +8 -7
  35. data/lib/ferrum/remote_object.rb +75 -0
  36. data/lib/ferrum/target.rb +7 -0
  37. data/lib/ferrum/utils/deprecate.rb +77 -0
  38. data/lib/ferrum/version.rb +1 -1
  39. data/lib/ferrum/worker.rb +8 -0
  40. data/lib/ferrum.rb +3 -0
  41. metadata +16 -2
@@ -27,32 +27,38 @@ module Ferrum
27
27
  #
28
28
  module DOM
29
29
  SCRIPT_SRC_TAG = <<~JS
30
- const script = document.createElement("script");
31
- script.src = arguments[0];
32
- script.type = arguments[1];
33
- script.onload = arguments[2];
34
- document.head.appendChild(script);
30
+ function(url, type) {
31
+ const script = document.createElement("script");
32
+ script.src = url;
33
+ script.type = type;
34
+ document.head.appendChild(script);
35
+ return new Promise(resolve => script.onload = resolve);
36
+ }
35
37
  JS
36
38
  SCRIPT_TEXT_TAG = <<~JS
37
- const script = document.createElement("script");
38
- script.text = arguments[0];
39
- script.type = arguments[1];
40
- document.head.appendChild(script);
41
- arguments[2]();
39
+ function(content, type) {
40
+ const script = document.createElement("script");
41
+ script.text = content;
42
+ script.type = type;
43
+ document.head.appendChild(script);
44
+ }
42
45
  JS
43
46
  STYLE_TAG = <<~JS
44
- const style = document.createElement("style");
45
- style.type = "text/css";
46
- style.appendChild(document.createTextNode(arguments[0]));
47
- document.head.appendChild(style);
48
- arguments[1]();
47
+ function(content) {
48
+ const style = document.createElement("style");
49
+ style.type = "text/css";
50
+ style.appendChild(document.createTextNode(content));
51
+ document.head.appendChild(style);
52
+ }
49
53
  JS
50
54
  LINK_TAG = <<~JS
51
- const link = document.createElement("link");
52
- link.rel = "stylesheet";
53
- link.href = arguments[0];
54
- link.onload = arguments[1];
55
- document.head.appendChild(link);
55
+ function(url) {
56
+ const link = document.createElement("link");
57
+ link.rel = "stylesheet";
58
+ link.href = url;
59
+ document.head.appendChild(link);
60
+ return new Promise(resolve => link.onload = resolve);
61
+ }
56
62
  JS
57
63
 
58
64
  #
@@ -160,7 +166,7 @@ module Ferrum
160
166
  }
161
167
  JS
162
168
 
163
- evaluate_func(expr, selector, within)
169
+ evaluate(expr, selector, within)
164
170
  end
165
171
 
166
172
  #
@@ -187,7 +193,7 @@ module Ferrum
187
193
  return xpath.snapshotItem(0);
188
194
  }
189
195
  JS
190
- evaluate_func(expr, selector, within)
196
+ evaluate(expr, selector, within)
191
197
  end
192
198
 
193
199
  #
@@ -214,7 +220,7 @@ module Ferrum
214
220
  }
215
221
  JS
216
222
 
217
- evaluate_func(expr, selector, within)
223
+ evaluate(expr, selector, within)
218
224
  end
219
225
 
220
226
  #
@@ -241,7 +247,7 @@ module Ferrum
241
247
  }
242
248
  JS
243
249
 
244
- evaluate_func(expr, selector, within)
250
+ evaluate(expr, selector, within)
245
251
  end
246
252
 
247
253
  #
@@ -307,17 +313,17 @@ module Ferrum
307
313
  # browser.add_script_tag(url: "http://example.com/stylesheet.css") # => true
308
314
  #
309
315
  def add_script_tag(url: nil, path: nil, content: nil, type: "text/javascript")
310
- expr, *args = if url
311
- [SCRIPT_SRC_TAG, url, type]
312
- elsif path || content
313
- if path
314
- content = File.read(path)
315
- content += "\n//# sourceURL=#{path}"
316
- end
317
- [SCRIPT_TEXT_TAG, content, type]
318
- end
316
+ if url
317
+ evaluate(SCRIPT_SRC_TAG, url, type)
318
+ elsif path || content
319
+ if path
320
+ content = File.read(path)
321
+ content += "\n//# sourceURL=#{path}"
322
+ end
323
+ evaluate(SCRIPT_TEXT_TAG, content, type)
324
+ end
319
325
 
320
- evaluate_async(expr, @page.timeout, *args)
326
+ true
321
327
  end
322
328
 
323
329
  #
@@ -333,17 +339,17 @@ module Ferrum
333
339
  # browser.add_style_tag(content: "h1 { font-size: 40px; }") # => true
334
340
  #
335
341
  def add_style_tag(url: nil, path: nil, content: nil)
336
- expr, *args = if url
337
- [LINK_TAG, url]
338
- elsif path || content
339
- if path
340
- content = File.read(path)
341
- content += "\n//# sourceURL=#{path}"
342
- end
343
- [STYLE_TAG, content]
344
- end
342
+ if url
343
+ evaluate(LINK_TAG, url)
344
+ elsif path || content
345
+ if path
346
+ content = File.read(path)
347
+ content += "\n//# sourceURL=#{path}"
348
+ end
349
+ evaluate(STYLE_TAG, content)
350
+ end
345
351
 
346
- evaluate_async(expr, @page.timeout, *args)
352
+ true
347
353
  end
348
354
  end
349
355
  end
@@ -0,0 +1,336 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Ferrum
4
+ class Frame
5
+ module Runtime
6
+ #
7
+ # The JavaScript evaluation API as it was before named arguments, kept
8
+ # so that scripts written for it return exactly what they used to. A
9
+ # call takes this path unless `FERRUM_JS_API=new` is set or the call
10
+ # uses something only the new API has: named arguments, a function
11
+ # declaration, `await`, or one of the new methods.
12
+ #
13
+ # Whatever runs here is checked for what Ferrum 0.21 will do
14
+ # differently, which is warned about with a suggested rewrite. 0.21
15
+ # removes this module, leaving only the new way.
16
+ #
17
+ # The script is parsed by {Script} as for the new way, to route the
18
+ # call and to spot what changes. An old-style call then runs as it did
19
+ # in Ferrum 0.19:
20
+ #
21
+ # 1. **Arguments.** Keyword arguments, `timeout:` included, are
22
+ # appended to the positional ones as one trailing object.
23
+ # 2. **Wrap.** The source is wrapped as it is, in
24
+ # `function() { return <source> }`, or `function() { <source> }` for
25
+ # {#execute}. A line break after `return` ends that statement, and
26
+ # only the first statement of `"a(); b"` runs.
27
+ # 3. **Call.** One `Runtime.callFunctionOn` that doesn't await
28
+ # promises, bounded by the page timeout, which raises a plain
29
+ # {TimeoutError}. {#evaluate_async} races the promise against a
30
+ # timer in the page instead.
31
+ # 4. **Check.** Before the result is converted, it's compared with what
32
+ # 0.21 will do: its subtype for promises, nodes and dates, its
33
+ # properties for nodes in an array, and the parsed script for
34
+ # statements separated by a semicolon. Nothing is
35
+ # run on the result, so getters and proxy traps don't fire.
36
+ # 5. **Warn.** Each difference warns once per call site, naming the
37
+ # first caller outside installed gems, then the result is converted
38
+ # as before: a promise comes back as `{}`.
39
+ #
40
+ module Legacy
41
+ # Marker rejected browser-side by {#evaluate_async} when it times out.
42
+ TIMEOUT_MARKER = "timed out promise"
43
+
44
+ NEXT_VERSION = "Ferrum 0.21"
45
+
46
+ #
47
+ # @deprecated Will be removed in Ferrum 0.21. Use {#evaluate}, which awaits
48
+ # promises: `page.evaluate("await thing()", timeout: wait)`.
49
+ #
50
+ # Evaluates an asynchronous expression, appending a resolve callback as
51
+ # the last entry of `arguments`.
52
+ #
53
+ # @param [String] expression
54
+ # The JavaScript to evaluate.
55
+ #
56
+ # @param [Integer] wait
57
+ # How long to wait for the promise to settle, in seconds.
58
+ #
59
+ # @param [Array] args
60
+ # Additional arguments, reachable as `arguments[0]` and up. The
61
+ # resolve callback follows them.
62
+ #
63
+ # @return [Object]
64
+ #
65
+ def evaluate_async(expression, wait, *args)
66
+ Utils::Deprecate.warn(
67
+ "#{self.class}#evaluate_async will be removed in Ferrum 0.21. Use #evaluate, which waits for a " \
68
+ "returned promise, instead of calling the last of `arguments`: " \
69
+ "evaluate(\"await new Promise(resolve => setTimeout(resolve, 100))\", timeout: #{wait})."
70
+ )
71
+
72
+ template = <<~JS
73
+ function() {
74
+ return new Promise((__f, __r) => {
75
+ try {
76
+ arguments[arguments.length] = r => __f(r);
77
+ arguments.length = arguments.length + 1;
78
+ setTimeout(() => __r(new Error("#{TIMEOUT_MARKER}")), %s);
79
+ %s
80
+ } catch(error) {
81
+ __r(error);
82
+ }
83
+ });
84
+ }
85
+ JS
86
+
87
+ expression = format(template, wait * 1000, expression)
88
+ legacy_call(expression: expression, arguments: args, awaitPromise: true)
89
+ end
90
+
91
+ #
92
+ # @deprecated Will be removed in Ferrum 0.21. Use {#evaluate}, which takes a
93
+ # function declaration and named arguments, or {Node#evaluate}.
94
+ #
95
+ # Evaluates a raw JS function declaration, optionally on a specific
96
+ # remote object instead of the frame's global execution context.
97
+ #
98
+ # @param [String] expression
99
+ # A JS function declaration, e.g. `"function(a, b) { return a + b }"`.
100
+ #
101
+ # @param [Array] args
102
+ # Arguments to pass to the function.
103
+ #
104
+ # @param [Node, nil] on
105
+ # Remote object to invoke the function on.
106
+ #
107
+ # @return [Object]
108
+ #
109
+ def evaluate_func(expression, *args, on: nil)
110
+ Utils::Deprecate.warn(
111
+ "#{self.class}#evaluate_func will be removed in Ferrum 0.21. Use #evaluate, which takes a function " \
112
+ "declaration: evaluate(\"function(a, b) { return a + b }\", 1, 2). " \
113
+ "For on:, use node.evaluate."
114
+ )
115
+
116
+ legacy_call(expression: expression, arguments: args, on: on)
117
+ end
118
+
119
+ #
120
+ # @deprecated Will be removed in Ferrum 0.21. Use {Node#evaluate}.
121
+ #
122
+ # Evaluates an expression against a given node's remote object (+this+
123
+ # refers to the node).
124
+ #
125
+ # @param [Node] node
126
+ # The node to evaluate the expression on.
127
+ #
128
+ # @param [String] expression
129
+ # The JavaScript to evaluate.
130
+ #
131
+ # @param [Boolean] by_value
132
+ # Whether to return the plain JS value instead of resolving it.
133
+ #
134
+ # @param [Integer] wait
135
+ # Passed through to the underlying `Runtime.callFunctionOn` command.
136
+ #
137
+ # @return [Object]
138
+ #
139
+ def evaluate_on(node:, expression:, by_value: true, wait: 0)
140
+ replacement = 'node.evaluate("this.value")'
141
+ replacement = "page.wait_for_navigation!(#{wait}) { #{replacement} }" if wait.positive?
142
+ Utils::Deprecate.warn("#{self.class}#evaluate_on will be removed in Ferrum 0.21. Use #{replacement} instead.")
143
+
144
+ options = { handle: true }
145
+ expression = format("function() { return %s }", expression)
146
+ options = { handle: false, returnByValue: true } if by_value
147
+ legacy_call(expression: expression, on: node, wait: wait, **options)
148
+ end
149
+
150
+ private
151
+
152
+ # Calls that only the new API could have made go the new way.
153
+ def legacy?(script, positional, keywords, mode:, on:)
154
+ return false if ENV.fetch("FERRUM_JS_API", nil) == "new"
155
+ return false if mode == :handle || (on && (mode == :none || !on.is_a?(Node)))
156
+ return false if script.declaration? || script.awaits?
157
+
158
+ keywords.empty? || positional.any? || script.uses?("arguments")
159
+ end
160
+
161
+ # Keywords used to be collected into a trailing Hash, `timeout:`
162
+ # included, so they're passed on exactly that way.
163
+ def run_legacy(script, positional, keywords, mode:, on:)
164
+ warn_about_keywords(script, positional, keywords)
165
+ arguments = keywords.empty? ? positional : [*positional, keywords]
166
+
167
+ if mode == :none
168
+ legacy_execute(script, arguments)
169
+ elsif on
170
+ legacy_evaluate_on(script, arguments, on)
171
+ else
172
+ legacy_evaluate(script, arguments)
173
+ end
174
+ end
175
+
176
+ def legacy_evaluate(script, arguments)
177
+ warn_about_line_break(script)
178
+ response = legacy_call(expression: format("function() { return %s }", script.source),
179
+ arguments: arguments, handle: :raw, serializationOptions: DEEP_SERIALIZATION)
180
+ legacy_handle_error(response)
181
+ warn_about_result(script, response, :value)
182
+ warn_about_statements(script)
183
+ handle_response(response["result"])
184
+ end
185
+
186
+ def legacy_evaluate_on(script, arguments, node)
187
+ warn_about_line_break(script)
188
+ response = legacy_call(expression: format("function() { return %s }", script.source),
189
+ arguments: arguments, on: node, handle: :raw)
190
+ legacy_handle_error(response)
191
+ warn_about_result(script, response, :node)
192
+ warn_about_statements(script)
193
+ serialize(response["result"])
194
+ end
195
+
196
+ def legacy_execute(script, arguments)
197
+ response = legacy_call(expression: format("function() { %s }", script.source),
198
+ arguments: arguments, handle: :raw)
199
+ legacy_handle_error(response)
200
+ warn_about_result(script, response, :none)
201
+ release(response["result"])
202
+ true
203
+ end
204
+
205
+ # What `returnByValue` used to give, fetched afterwards so that the
206
+ # result could be inspected first.
207
+ def serialize(result)
208
+ object_id = result["objectId"]
209
+ return result["value"] unless object_id
210
+
211
+ response = @page.command("Runtime.callFunctionOn", objectId: object_id, returnByValue: true,
212
+ functionDeclaration: "function() { return this }")
213
+ response.dig("result", "value")
214
+ ensure
215
+ release(result)
216
+ end
217
+
218
+ def release(result)
219
+ object_id = result&.dig("objectId")
220
+ @page.command("Runtime.releaseObject", objectId: object_id) if object_id
221
+ rescue BrowserError
222
+ nil
223
+ end
224
+
225
+ def legacy_call(expression:, arguments: [], on: nil, wait: 0, handle: true, **options)
226
+ # do not rescue -> retry if we operate on an existing node
227
+ errors = on ? [] : [NodeNotFoundError, NoExecutionContextError]
228
+
229
+ Utils::Attempt.with_retry(errors: errors, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP) do
230
+ params = options.dup
231
+
232
+ params = params.merge(objectId: resolve_node(on)) if on
233
+ params = params.merge(serializationOptions: DEEP_SERIALIZATION) if handle == true
234
+
235
+ if params[:executionContextId].nil? && params[:objectId].nil?
236
+ params = params.merge(executionContextId: execution_id!)
237
+ end
238
+
239
+ response = @page.command("Runtime.callFunctionOn",
240
+ wait: wait, slowmoable: true,
241
+ **params.merge(functionDeclaration: expression,
242
+ arguments: prepare_args(arguments)))
243
+ next response if handle == :raw
244
+
245
+ legacy_handle_error(response)
246
+ response = response["result"]
247
+
248
+ handle ? handle_response(response) : response["value"]
249
+ end
250
+ end
251
+
252
+ def legacy_handle_error(response)
253
+ details = response["exceptionDetails"]
254
+ return unless details
255
+
256
+ description = details.dig("exception", "description").to_s
257
+ raise ScriptTimeoutError if description.start_with?("Error: #{TIMEOUT_MARKER}")
258
+
259
+ raise JavaScriptError, details
260
+ end
261
+
262
+ def warn_about_keywords(script, positional, keywords)
263
+ return if keywords.empty?
264
+
265
+ if positional.any?
266
+ warn_about(script, "Mixing positional and keyword arguments will raise ArgumentError in #{NEXT_VERSION}, " \
267
+ "where keywords will become named parameters instead of a trailing object. Pass the " \
268
+ "object in braces, evaluate(\"…\", 1, { foo: 1 }), or name every argument.")
269
+ else
270
+ warn_about(script, "Keyword arguments will become named parameters in #{NEXT_VERSION} instead of " \
271
+ "arriving as one object in `arguments[0]`. Name the object instead: " \
272
+ "evaluate(\"options.foo\", options: { foo: 1 }).")
273
+ end
274
+ end
275
+
276
+ def warn_about_line_break(script)
277
+ return unless script.leading_line_break?
278
+
279
+ warn_about(script, "This script never runs: the line break before it ends the `return` it's placed " \
280
+ "after, so the result is always nil. #{NEXT_VERSION} will run it and return its value. " \
281
+ "Check it's safe to run, or remove it.")
282
+ end
283
+
284
+ def warn_about_statements(script)
285
+ return if script.leading_line_break? || !script.several_statements?
286
+
287
+ warn_about(script, "This script is more than one statement, and today only the first one runs. " \
288
+ "#{NEXT_VERSION} will run them all and return the value of the last one. Check the " \
289
+ "rest is safe to run, or remove it.")
290
+ end
291
+
292
+ def warn_about_result(script, response, kind)
293
+ result = response["result"]
294
+ case result["subtype"]
295
+ when "promise" then warn_about_promise(script, kind)
296
+ when "node" then warn_about_node(script, "a DOM node", "Ferrum::Node") if kind == :node
297
+ when "date" then warn_about_node(script, "a Date", "its ISO 8601 string") if kind == :node
298
+ when "array" then warn_about_nodes(script, result) if kind == :node
299
+ end
300
+ end
301
+
302
+ def warn_about_promise(script, kind)
303
+ if kind == :none
304
+ warn_about(script, "This script returns a promise, which #execute will wait for in #{NEXT_VERSION}. " \
305
+ "Drop the `return`, or use `void`, to keep it from waiting.")
306
+ else
307
+ warn_about(script, "This script returns a promise, which comes back as {} today. #{NEXT_VERSION} " \
308
+ "will wait for it and return its value, or raise if it rejects. Prefix the " \
309
+ "expression with `void` to keep it from waiting.")
310
+ end
311
+ end
312
+
313
+ def warn_about_node(script, value, replacement)
314
+ warn_about(script, "Node#evaluate returns #{value} as {} today, and will return #{replacement} in " \
315
+ "#{NEXT_VERSION}. Check the code that uses the result.")
316
+ end
317
+
318
+ def warn_about_nodes(script, result)
319
+ nodes = properties(result, ownProperties: true).any? { |p| p.dig("value", "subtype") == "node" }
320
+ warn_about_node(script, "DOM nodes in an array", "Ferrum::Node") if nodes
321
+ end
322
+
323
+ def properties(result, **options)
324
+ @page.command("Runtime.getProperties", objectId: result["objectId"], **options)["result"]
325
+ end
326
+
327
+ def warn_about(script, message)
328
+ excerpt = script.code.lines.first.to_s.strip
329
+ excerpt = "#{excerpt[0, 60]}…" if excerpt.length > 60 || script.code.lines.size > 1
330
+ Utils::Deprecate.warn("#{message} Set FERRUM_JS_API=new to run it the #{NEXT_VERSION} way now." \
331
+ "\n script: #{excerpt}", user_code: true)
332
+ end
333
+ end
334
+ end
335
+ end
336
+ end