ferrum 0.19.1 → 0.20.0

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 +93 -73
  9. data/lib/ferrum/client.rb +9 -5
  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 +10 -3
  32. data/lib/ferrum/page/screenshot.rb +8 -7
  33. data/lib/ferrum/page.rb +106 -53
  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
@@ -1,13 +1,14 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "singleton"
4
+ require "ferrum/frame/script"
5
+ require "ferrum/frame/runtime/legacy"
4
6
 
5
7
  module Ferrum
6
8
  #
7
- # Placeholder object substituted for a JavaScript value that couldn't be
8
- # fully serialized because it contains circular references. It exists
9
- # only so that {#inspect} can report the situation instead of the
10
- # evaluation raising or hanging.
9
+ # Placeholder substituted for a reference back to a JavaScript object that
10
+ # contains it, e.g. `a.self = a`, so that the result stays a finite Ruby
11
+ # Hash or Array.
11
12
  #
12
13
  class CyclicObject
13
14
  include Singleton
@@ -22,262 +23,491 @@ module Ferrum
22
23
 
23
24
  class Frame
24
25
  #
25
- # Evaluates and executes JavaScript in a frame's execution context via
26
+ # Runs JavaScript in a frame's execution context via
26
27
  # `Runtime.callFunctionOn`, converting arguments and return values
27
- # between Ruby and JS, and resolving object/array/node results
28
- # (including cyclic ones, via {CyclicObject}) into Ruby equivalents.
28
+ # between Ruby and JS, and resolving object/array/node results into Ruby
29
+ # equivalents. A reference back to an enclosing object becomes
30
+ # {CyclicObject}.
31
+ #
32
+ # There are three entry points, all of which accept the script in the
33
+ # same two shapes and pass arguments the same way:
34
+ #
35
+ # * {#evaluate} returns the value, serialized into Ruby.
36
+ # * {#evaluate_handle} returns a {RemoteObject} that stays in the browser.
37
+ # * {#execute} discards the value and returns `true`.
38
+ #
39
+ # ## Script shapes
40
+ #
41
+ # A script is either code that gets wrapped in a function for you and
42
+ # returns the value of its last statement, or a function declaration,
43
+ # which is used as-is.
44
+ #
45
+ # page.evaluate("window.scrollY")
46
+ # page.evaluate("const a = 1\na + 1")
47
+ # page.evaluate("function() { const a = 1; return a + 1 }")
48
+ #
49
+ # Arrow functions keep the `this` of where they're defined, so on a
50
+ # {Node} use a `function` declaration when the script needs `this`.
51
+ #
52
+ # ## Arguments
53
+ #
54
+ # Keyword arguments become the function's parameters, so the script can
55
+ # name what it receives instead of digging through `arguments[0]`:
56
+ #
57
+ # page.evaluate("a + b", a: 1, b: 2)
58
+ #
59
+ # Each keyword is sent as its own protocol argument, so a {Node} arrives
60
+ # in JavaScript as the live element rather than as serialized JSON.
61
+ #
62
+ # A function declaration names its parameters itself, so it takes
63
+ # positional arguments, in the order it declares them:
64
+ #
65
+ # page.evaluate("function(a, b) { return a + b }", 1, 2)
66
+ #
67
+ # Positional arguments also work with an expression, landing in
68
+ # `arguments[0]` and up, but can't be mixed with keyword ones.
69
+ #
70
+ # `timeout:` is reserved for Ferrum, so a variable of the script can't
71
+ # take that name.
72
+ #
73
+ # ## Promises
74
+ #
75
+ # A returned promise, or any object with a `then` method, is awaited, so
76
+ # `async`/`await` works directly and there is no separate asynchronous
77
+ # method:
78
+ #
79
+ # page.evaluate("await fetch(url).then(r => r.text())", url: "/api")
80
+ #
81
+ # ## Timeouts
82
+ #
83
+ # If the script hasn't settled within `timeout:` seconds (defaulting to
84
+ # the page's timeout) a {ScriptTimeoutError} is raised.
85
+ #
86
+ # The timeout is how long Ruby waits for Chrome's answer, so a page that
87
+ # replaces `Promise` or `setTimeout` can't defeat it, but it doesn't stop
88
+ # the script. A promise that never settles is harmless, while a
89
+ # synchronous endless loop keeps the page's JavaScript busy, so later
90
+ # calls on that page time out too. Other pages aren't affected.
91
+ #
92
+ # ## How a call runs
93
+ #
94
+ # All three methods, and their {Node} counterparts through
95
+ # {#evaluate_in}, take the same steps and differ only in a mode:
96
+ # `:value`, `:handle` or `:none`.
97
+ #
98
+ # 1. **Parse.** {Script} reads the source once, skipping strings,
99
+ # template literals, regular expressions and comments. It finds the
100
+ # code without surrounding comments and semicolons, whether it's a
101
+ # function or arrow declaration, where its last statement starts, and
102
+ # whether it uses `await`.
103
+ # 2. **Arguments.** `timeout:` is taken out of the keywords.
104
+ # Positional arguments are passed as they are. Named ones become the
105
+ # parameters of the function an expression is wrapped in, and raise
106
+ # for a declaration, which names its parameters itself.
107
+ # 3. **Wrap.** A declaration is sent as it is. An expression becomes
108
+ # `function(<names>) { return (<code>) }`, `async` when it uses
109
+ # `await`. Of several statements, only the last is returned, as in
110
+ # `function() { a(); return (b) }`. {#execute} uses the script as
111
+ # written as the function body instead.
112
+ # 4. **Call.** One `Runtime.callFunctionOn` in the frame's context, or
113
+ # with `this` bound to a node or remote object. When it returns a
114
+ # promise or a plain object, a second call awaits it, which isn't
115
+ # retried after a navigation, as the script has already run. {Node}
116
+ # and {RemoteObject} arguments are passed by reference.
117
+ # 5. **Result.** {#evaluate} converts Chrome's deep serialization into
118
+ # Ruby, {#evaluate_handle} wraps an object in a {RemoteObject}, and
119
+ # {#execute} returns `true`. A thrown value raises {JavaScriptError}.
120
+ #
121
+ # For example, this call:
122
+ #
123
+ # page.evaluate("await fetch(url).then(r => r.status)", url: "/ping")
124
+ #
125
+ # is an expression that uses `await`, so it's sent as:
126
+ #
127
+ # async function(url) {
128
+ # return (
129
+ # await fetch(url).then(r => r.status)
130
+ # );
131
+ # }
132
+ #
133
+ # with the arguments `[{ value: "/ping" }]`. Chrome answers with a
134
+ # promise, a second call awaits it and gets
135
+ # `{ type: "number", value: 200 }`, which comes back as
136
+ # `200`. A declaration takes positional arguments instead:
137
+ #
138
+ # node.evaluate("function(prefix, suffix) { return prefix + this.id + suffix }", "#", "!")
139
+ #
140
+ # is sent unchanged, with `this` bound to the node and the arguments
141
+ # `["#", "!"]`, and comes back as `"#main!"`.
142
+ #
143
+ # ## Scripts written for the old API
144
+ #
145
+ # Until Ferrum 0.21, a call that only the old API could have made runs
146
+ # the old way through {Legacy} and warns when its result will change.
147
+ # That's a call without named arguments, or one whose script reads
148
+ # `arguments` or also passes positional ones, unless the script is a
149
+ # declaration or uses `await`, or the method is {#evaluate_handle} or
150
+ # {Node#execute}.
151
+ # `FERRUM_JS_API=new` sends every call through the steps above.
29
152
  #
30
153
  module Runtime
154
+ include Legacy
155
+
31
156
  INTERMITTENT_ATTEMPTS = ENV.fetch("FERRUM_INTERMITTENT_ATTEMPTS", 6).to_i
32
157
  INTERMITTENT_SLEEP = ENV.fetch("FERRUM_INTERMITTENT_SLEEP", 0.1).to_f
158
+ DEEP_SERIALIZATION = {
159
+ serialization: "deep",
160
+ additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" }
161
+ }.freeze
162
+ # Describes a primitive or node result, which a handle can't stand for,
163
+ # without serializing an object that stays in the browser.
164
+ SHALLOW_SERIALIZATION = DEEP_SERIALIZATION.merge(maxDepth: 0).freeze
165
+ UNSERIALIZABLE_NUMBERS = {
166
+ "NaN" => Float::NAN,
167
+ "-0" => -0.0,
168
+ "Infinity" => Float::INFINITY,
169
+ "-Infinity" => -Float::INFINITY
170
+ }.freeze
33
171
 
34
172
  #
35
- # Evaluate and return result for given JS expression.
173
+ # Evaluates JavaScript and returns the result, serialized into Ruby.
36
174
  #
37
175
  # @param [String] expression
38
- # The JavaScript to evaluate.
176
+ # A JavaScript expression, or a function declaration.
177
+ #
178
+ # @param [Array] positional
179
+ # Arguments reachable as `arguments[0]` and up. Can't be combined
180
+ # with named ones.
39
181
  #
40
- # @param [Array] args
41
- # Additional arguments to pass to the JavaScript code.
182
+ # @param [Hash] keywords
183
+ # Named arguments, which become the function's parameters, plus:
184
+ #
185
+ # @option keywords [Numeric, nil] :timeout
186
+ # How long to wait for the script, and any promise it returns, to
187
+ # settle, in seconds. Defaults to the page timeout.
188
+ #
189
+ # @return [Object]
190
+ # The result. DOM nodes come back as {Node}, arrays and plain objects
191
+ # are converted recursively, and cyclic values become {CyclicObject}.
192
+ #
193
+ # @raise [ScriptTimeoutError]
194
+ # The script didn't settle within `timeout`.
195
+ #
196
+ # @raise [JavaScriptError]
197
+ # The script threw.
42
198
  #
43
199
  # @example
44
- # browser.evaluate("[window.scrollX, window.scrollY]")
200
+ # browser.evaluate("[window.scrollX, window.scrollY]") # => [0, 0]
201
+ # browser.evaluate("a + b", a: 1, b: 2) # => 3
202
+ # browser.evaluate("await fetch(url).then(r => r.status)", url: "/") # => 200
45
203
  #
46
- def evaluate(expression, *args)
47
- expression = format("function() { return %s }", expression)
48
- call(expression: expression, arguments: args)
204
+ def evaluate(expression, *positional, **keywords)
205
+ run(expression, positional, keywords, mode: :value)
49
206
  end
50
207
 
51
208
  #
52
- # Evaluate asynchronous expression and return result.
53
- #
54
- # @param [String] expression
55
- # The JavaScript to evaluate.
209
+ # Same as {#evaluate}, but returns a {RemoteObject} that keeps the value
210
+ # in the browser instead of serializing it. Handles can be passed back
211
+ # in as arguments. Primitives are returned as-is, and DOM nodes as
212
+ # {Node}, since both are already usable from Ruby.
56
213
  #
57
- # @param [Integer] wait
58
- # How long we should wait for Promise to resolve or reject.
214
+ # @param (see #evaluate)
215
+ # @option (see #evaluate)
59
216
  #
60
- # @param [Array] args
61
- # Additional arguments to pass to the JavaScript code.
217
+ # @return [RemoteObject, Node, Object]
62
218
  #
63
219
  # @example
64
- # browser.evaluate_async(%(arguments[0]({foo: "bar"})), 5) # => { "foo" => "bar" }
65
- #
66
- def evaluate_async(expression, wait, *args)
67
- template = <<~JS
68
- function() {
69
- return new Promise((__f, __r) => {
70
- try {
71
- arguments[arguments.length] = r => __f(r);
72
- arguments.length = arguments.length + 1;
73
- setTimeout(() => __r(new Error("timed out promise")), %s);
74
- %s
75
- } catch(error) {
76
- __r(error);
77
- }
78
- });
79
- }
80
- JS
81
-
82
- expression = format(template, wait * 1000, expression)
83
- call(expression: expression, arguments: args, awaitPromise: true)
220
+ # list = page.evaluate_handle("document.querySelectorAll('li')")
221
+ # page.evaluate("Array.from(nodes).map(n => n.textContent)", nodes: list)
222
+ #
223
+ def evaluate_handle(expression, *positional, **keywords)
224
+ run(expression, positional, keywords, mode: :handle)
84
225
  end
85
226
 
86
227
  #
87
- # Execute expression. Doesn't return the result.
228
+ # Runs JavaScript for its side effects and discards the result. Unlike
229
+ # {#evaluate}, the script is used as a function body rather than an
230
+ # expression, so multiple statements need no wrapping.
88
231
  #
89
- # @param [String] expression
90
- # The JavaScript to evaluate.
232
+ # @param (see #evaluate)
233
+ # @option (see #evaluate)
91
234
  #
92
- # @param [Array] args
93
- # Additional arguments to pass to the JavaScript code.
235
+ # @return [Boolean]
236
+ # Always `true`.
94
237
  #
95
238
  # @example
96
- # browser.execute(%(1 + 1)) # => true
239
+ # browser.execute("window.scrollBy(0, 100)") # => true
240
+ # browser.execute(<<~JS, url: "/next")
241
+ # history.pushState({}, "", url);
242
+ # window.dispatchEvent(new Event("popstate"));
243
+ # JS
97
244
  #
98
- def execute(expression, *args)
99
- expression = format("function() { %s }", expression)
100
- call(expression: expression, arguments: args, handle: false, returnByValue: true)
245
+ def execute(expression, *positional, **keywords)
246
+ run(expression, positional, keywords, mode: :none)
101
247
  true
102
248
  end
103
249
 
104
250
  #
105
- # Evaluates a raw JS function declaration (unlike {#evaluate}, which
106
- # wraps the given expression in one), optionally on a specific remote
107
- # object instead of the frame's global execution context.
251
+ # @api private
108
252
  #
109
- # @param [String] expression
110
- # A JS function declaration, e.g. `"function(a, b) { return a + b }"`.
253
+ # Backs {Node#evaluate}, {Node#evaluate_handle}, {Node#execute} and
254
+ # {RemoteObject#value}. Runs the script with `this` bound to `object`,
255
+ # using the same argument and script conventions as {#evaluate}.
256
+ #
257
+ # @param [Node, RemoteObject] object
258
+ # The node or object to bind `this` to.
111
259
  #
112
- # @param [Array] args
113
- # Arguments to pass to the function.
260
+ # @param [Symbol] mode
261
+ # `:value`, `:handle` or `:none`.
114
262
  #
115
- # @param [Node, nil] on
116
- # Remote object to invoke the function on.
263
+ # @return [Object]
117
264
  #
118
- def evaluate_func(expression, *args, on: nil)
119
- call(expression: expression, arguments: args, on: on)
265
+ def evaluate_in(object, expression, positional, keywords, mode: :value)
266
+ run(expression, positional, keywords, mode: mode, on: object)
120
267
  end
121
268
 
269
+ private
270
+
122
271
  #
123
- # Evaluates an expression against a given node's remote object (+this+
124
- # refers to the node), returning the raw JS value rather than
125
- # resolving it to a {Node}/Hash/Array.
272
+ # Parses the script, turns the arguments into a parameter list and
273
+ # values, wraps the script into the function declaration that's sent,
274
+ # and hands it to {#call}. `mode` decides both how the result is
275
+ # converted and whether the script's value is kept.
126
276
  #
127
- # @param [Node] node
128
- # The node to evaluate the expression on.
277
+ def run(expression, positional, keywords, mode:, on: nil)
278
+ script = Script.new(expression)
279
+ if legacy?(script, positional, keywords, mode: mode, on: on)
280
+ return run_legacy(script, positional, keywords, mode: mode, on: on)
281
+ end
282
+
283
+ named = keywords.except(:timeout)
284
+ params, values = arguments_for(script, positional, named)
285
+ call(wrap(script, params, mode), values, on: on, mode: mode, timeout: script_timeout(keywords[:timeout]))
286
+ end
287
+
129
288
  #
130
- # @param [String] expression
131
- # The JavaScript to evaluate.
289
+ # Normalizes the two argument styles into the parameter names of the
290
+ # wrapping function and the values to send:
291
+ #
292
+ # * positional ones: no names, values reachable as `arguments[0]` and up,
293
+ # or as a declaration's own parameters;
294
+ # * named ones for an expression: their names and their values. A
295
+ # declaration names its parameters itself, so it takes positional
296
+ # ones only.
297
+ #
298
+ def arguments_for(script, positional, named)
299
+ if positional.any?
300
+ raise ArgumentError, "Pass arguments either positionally or by name, not both" if named.any?
301
+
302
+ return [[], positional]
303
+ end
304
+
305
+ return [[], []] if named.empty?
306
+ if script.declaration?
307
+ raise ArgumentError, "A function declaration names its own parameters, so pass its arguments " \
308
+ "positionally: evaluate(\"function(a, b) { … }\", 1, 2)"
309
+ end
310
+
311
+ [named.keys.map(&:to_s), named.values]
312
+ end
313
+
132
314
  #
133
- # @param [Boolean] by_value
134
- # Whether to return the plain JS value instead of a handle.
315
+ # Builds the function declaration that is actually sent to the browser:
316
+ # the caller's declaration as-is, or an expression wrapped in one.
135
317
  #
136
- # @param [Integer] wait
137
- # Passed through to the underlying `Runtime.callFunctionOn` command.
318
+ # wrap(Script.new("a + b"), %w[a b], :value)
319
+ # # => "function(a, b) { return (a + b\n);\n}"
320
+ # wrap(Script.new("await x()"), [], :none)
321
+ # # => "async function() { await x()\n}"
138
322
  #
139
- def evaluate_on(node:, expression:, by_value: true, wait: 0)
140
- options = { handle: true }
141
- expression = format("function() { return %s }", expression)
142
- options = { handle: false, returnByValue: true } if by_value
143
- call(expression: expression, on: node, wait: wait, **options)
323
+ def wrap(script, params, mode)
324
+ return script.code if script.declaration?
325
+
326
+ # A body keeps its trailing semicolons, which can be statements of
327
+ # their own, as in `while (busy());`. Otherwise the last statement is
328
+ # returned, parenthesized so that automatic semicolon insertion can't
329
+ # end the `return`. The script starts on the first line, so that error
330
+ # locations match its lines.
331
+ head, last = script.split_last_statement
332
+ body = if mode == :none then script.source
333
+ elsif last.empty? then ""
334
+ elsif last.match?(Script::STATEMENT) then script.code
335
+ else "#{head}return (#{last}\n);"
336
+ end
337
+ "#{'async ' if script.awaits?}function(#{params.join(', ')}) { #{body}\n}"
144
338
  end
145
339
 
146
- private
340
+ # Waiting for the response is what bounds the script, so a page that
341
+ # replaces `Promise` or `setTimeout`, or throttles timers, can't defeat
342
+ # it.
343
+ def script_timeout(timeout)
344
+ (timeout || @page.timeout).to_f
345
+ end
147
346
 
148
- def call(expression:, arguments: [], on: nil, wait: 0, handle: true, **options)
347
+ #
348
+ # Sends the declaration with `Runtime.callFunctionOn`, retrying while
349
+ # the frame's context is being replaced unless `this` is bound to an
350
+ # existing node, and converts the result.
351
+ #
352
+ # @param [Symbol] mode
353
+ # `:value` resolves the result into Ruby, `:handle` returns a
354
+ # {RemoteObject}, and `:none` discards it.
355
+ #
356
+ def call(declaration, values, on:, mode:, timeout:)
149
357
  # do not rescue -> retry if we operate on an existing node
150
358
  errors = on ? [] : [NodeNotFoundError, NoExecutionContextError]
151
359
 
152
- Utils::Attempt.with_retry(errors: errors, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP) do
153
- params = options.dup
360
+ serialization = mode == :value ? DEEP_SERIALIZATION : SHALLOW_SERIALIZATION
361
+ response = Utils::Attempt.with_retry(errors: errors, max: INTERMITTENT_ATTEMPTS, wait: INTERMITTENT_SLEEP) do
362
+ call_function(declaration, values, call_target(on), serialization, timeout)
363
+ end
364
+ handle_error(response, declaration)
154
365
 
155
- if on
156
- response = @page.command("DOM.resolveNode", nodeId: on.node_id)
157
- object_id = response.dig("object", "objectId")
158
- params = params.merge(objectId: object_id)
159
- end
366
+ result = response["result"]
367
+ result = await_promise(result, serialization, timeout) if thenable?(result)
368
+ case mode
369
+ when :none then nil
370
+ when :handle then handle_remote_object(result)
371
+ else handle_response(result)
372
+ end
373
+ end
160
374
 
161
- if params[:executionContextId].nil? && params[:objectId].nil?
162
- params = params.merge(executionContextId: execution_id!)
163
- end
375
+ def call_function(declaration, values, target, serialization, timeout)
376
+ @page.command("Runtime.callFunctionOn",
377
+ timeout: timeout, slowmoable: true, serializationOptions: serialization,
378
+ functionDeclaration: declaration, arguments: prepare_args(values), **target)
379
+ rescue TimeoutError
380
+ raise ScriptTimeoutError
381
+ end
164
382
 
165
- response = @page.command("Runtime.callFunctionOn",
166
- wait: wait, slowmoable: true,
167
- **params.merge(functionDeclaration: expression,
168
- arguments: prepare_args(arguments)))
169
- handle_error(response)
170
- response = response["result"]
383
+ # A promise, or a plain object that may be one, such as the promises of
384
+ # zone.js or Bluebird, which Chrome doesn't report as `promise`.
385
+ def thenable?(result)
386
+ result["type"] == "object" && [nil, "promise"].include?(result["subtype"])
387
+ end
171
388
 
172
- handle ? handle_response(response) : response["value"]
389
+ # Awaited outside the retries: by now the script has run, and running
390
+ # it again after a navigation would repeat what it did. Awaiting an
391
+ # object that isn't thenable returns it as it is.
392
+ def await_promise(promise, serialization, timeout)
393
+ response = @page.command("Runtime.callFunctionOn",
394
+ timeout: timeout, awaitPromise: true, serializationOptions: serialization,
395
+ functionDeclaration: "function() { return this }", objectId: promise["objectId"])
396
+ handle_error(response)
397
+ response["result"]
398
+ rescue TimeoutError
399
+ raise ScriptTimeoutError
400
+ end
401
+
402
+ def call_target(on)
403
+ if on.is_a?(RemoteObject)
404
+ { objectId: on.remote_id }
405
+ elsif on
406
+ { objectId: resolve_node(on) }
407
+ else
408
+ { executionContextId: execution_id! }
173
409
  end
174
410
  end
175
411
 
176
- # FIXME: We should have a central place to handle all type of errors
177
- def handle_error(response)
178
- result = response["result"]
179
- return if result["subtype"] != "error"
412
+ # Chrome reports no location for a script that doesn't compile, so the
413
+ # function it compiled is added, wrapper included.
414
+ def handle_error(response, declaration = nil)
415
+ details = response["exceptionDetails"]
416
+ return unless details
180
417
 
181
- case result["description"]
182
- when /\AError: timed out promise/
183
- raise ScriptTimeoutError
184
- else
185
- raise JavaScriptError, response["exceptionDetails"]
418
+ if declaration && details["stackTrace"].nil? && details.dig("exception", "className") == "SyntaxError"
419
+ description = "#{details.dig('exception', 'description')}\n in: #{declaration[0, 500]}"
420
+ details = details.merge("exception" => details["exception"].merge("description" => description))
186
421
  end
422
+ raise JavaScriptError, details
187
423
  end
188
424
 
189
- def handle_response(response, check_cyclic: true)
190
- case response["type"]
191
- when "boolean", "number", "string"
192
- response["value"]
193
- when "undefined"
425
+ def handle_remote_object(result)
426
+ return RemoteObject.new(self, @page, result) if result["objectId"] && result["subtype"] != "node"
427
+
428
+ handle_response(result)
429
+ end
430
+
431
+ def handle_response(response)
432
+ deserialize(response["deepSerializedValue"])
433
+ end
434
+
435
+ # Chrome sends a shared object in full once and refers to it after
436
+ # that, so each one is converted once and reused, as the same object.
437
+ def deserialize(serialized, references = {}, path = [], converted = {})
438
+ reference = serialized["weakLocalObjectReference"]
439
+ if reference
440
+ return cyclic_object if path.include?(reference)
441
+ return converted[reference] if converted.key?(reference)
442
+
443
+ serialized = references[reference] ||= serialized
444
+ path += [reference]
445
+ end
446
+
447
+ result = convert(serialized, references, path, converted)
448
+ converted[reference] = result if reference
449
+ result
450
+ end
451
+
452
+ def convert(serialized, references, path, converted)
453
+ value = serialized["value"]
454
+ case serialized["type"]
455
+ when "undefined", "null", "symbol"
194
456
  nil
195
- when "function"
196
- {}
457
+ when "boolean", "string", "date"
458
+ value
459
+ when "number"
460
+ UNSERIALIZABLE_NUMBERS.fetch(value, value)
461
+ when "bigint"
462
+ Integer(value)
463
+ when "array", "nodelist", "htmlcollection"
464
+ value.map { |v| deserialize(v, references, path, converted) }
197
465
  when "object"
198
- object_id = response["objectId"]
199
-
200
- case response["subtype"]
201
- when "node"
202
- description = @page.command("DOM.describeNode", objectId: object_id)["node"]
203
- Node.new(self, @page.target_id, description, object_id: object_id)
204
- when "array"
205
- reduce_props(object_id, [], check_cyclic: check_cyclic) do |memo, key, value|
206
- next(memo) unless Integer(key, exception: false)
207
-
208
- value = value["objectId"] ? handle_response(value, check_cyclic: false) : value["value"]
209
- memo.insert(key.to_i, value)
210
- end.compact
211
- when "date"
212
- response["description"]
213
- when "null"
214
- nil
215
- else
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"]
218
- memo.merge(key => value)
219
- end
220
- end
466
+ value.to_h { |k, v| [k, deserialize(v, references, path, converted)] }
467
+ when "node"
468
+ Node.new(self, value)
469
+ else
470
+ {}
221
471
  end
222
472
  end
223
473
 
474
+ def resolve_node(node)
475
+ @page.command("DOM.resolveNode", nodeId: node.node_id, **resolve_node_options).dig("object", "objectId")
476
+ end
477
+
478
+ def resolve_node_options
479
+ {}
480
+ end
481
+
224
482
  def prepare_args(args)
225
483
  args.map do |arg|
226
- if arg.is_a?(Node)
227
- resolved = @page.command("DOM.resolveNode", nodeId: arg.node_id)
228
- { objectId: resolved["object"]["objectId"] }
229
- elsif arg.is_a?(Hash) && arg["objectId"]
230
- { objectId: arg["objectId"] }
231
- else
232
- { value: arg }
484
+ if nested_reference?(arg)
485
+ raise ArgumentError, "A Ferrum::Node or Ferrum::RemoteObject inside an Array or Hash can't be passed " \
486
+ "to JavaScript. Pass each one as its own argument"
233
487
  end
234
- end
235
- end
236
-
237
- def reduce_props(object_id, to, check_cyclic: true)
238
- if check_cyclic && cyclic?(object_id).dig("result", "value")
239
- to.is_a?(Array) ? [cyclic_object] : cyclic_object
240
- else
241
- props = @page.command("Runtime.getProperties", ownProperties: true, objectId: object_id)
242
- props["result"].reduce(to) do |memo, prop|
243
- next(memo) unless prop["enumerable"]
244
488
 
245
- yield(memo, prop["name"], prop["value"])
489
+ case arg
490
+ when Node
491
+ { objectId: resolve_node(arg) }
492
+ when RemoteObject
493
+ { objectId: arg.remote_id }
494
+ when Hash
495
+ arg["objectId"] ? { objectId: arg["objectId"] } : { value: arg }
496
+ else
497
+ { value: arg }
246
498
  end
247
499
  end
248
500
  end
249
501
 
250
- def cyclic?(object_id)
251
- @page.command(
252
- "Runtime.callFunctionOn",
253
- objectId: object_id,
254
- returnByValue: true,
255
- functionDeclaration: <<~JS
256
- function() {
257
- if (Array.isArray(this) &&
258
- this.every(e => e instanceof Node)) {
259
- return false;
260
- }
261
-
262
- function detectCycle(obj, seen) {
263
- if (typeof obj === "object") {
264
- if (seen.indexOf(obj) !== -1) {
265
- return true;
266
- }
267
- for (let key in obj) {
268
- if (obj.hasOwnProperty(key) && detectCycle(obj[key], seen.concat([obj]))) {
269
- return true;
270
- }
271
- }
272
- }
273
-
274
- return false;
275
- }
276
-
277
- return detectCycle(this, []);
278
- }
279
- JS
280
- )
502
+ # A protocol argument is either a value or a reference, so a node in
503
+ # an array or hash would only arrive as its `to_s`.
504
+ def nested_reference?(value)
505
+ children = case value
506
+ when Array then value
507
+ when Hash then value.values
508
+ else return false
509
+ end
510
+ children.any? { |v| v.is_a?(Node) || v.is_a?(RemoteObject) || nested_reference?(v) }
281
511
  end
282
512
 
283
513
  def cyclic_object