Module: Obxcura::Frame::Runtime

Included in:
Obxcura::Frame
Defined in:
lib/obxcura/frame/runtime.rb

Overview

Runtime: executing JavaScript in the frame's context. This is the side that reaches the Client and puts CDP commands on the wire; everything in DOM is built on top of #evaluate.

Ruby values cross into JS as real arguments (Runtime.callFunctionOn), not by being string-interpolated into source. Node-handle resolution, cyclic-node detection and a retry loop are deliberately left out.

Instance Method Summary collapse

Instance Method Details

#call_on(object_id, function_declaration, args = [], timeout: nil) ⇒ Object?

Call a function declaration bound to a specific remote object (its this). Used by #evaluate_func (bound to globalThis) and by Node reads (bound to the node's handle).

Parameters:

  • object_id (String) —

    the CDP objectId to bind as this.

  • function_declaration (String) —

    a JS function declaration.

  • args (Array) (defaults to: []) —

    values passed to the function.

  • timeout (Integer, nil) (defaults to: nil) —

    override for the client's reply timeout, e.g. for a call that awaits a slow in-page POST.

Returns:

  • (Object, nil) —

    the function's return value (JSON-decoded).

Raises:



57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/obxcura/frame/runtime.rb', line 57

def call_on(object_id, function_declaration, args = [], timeout: nil)
  handle_result(command(
    "Runtime.callFunctionOn",
    {
      functionDeclaration: function_declaration,
      objectId: object_id,
      arguments: args.map { |value| { value: value } },
      awaitPromise: true,
      returnByValue: true
    },
    timeout: timeout
  ))
end

#evaluate(expression, *args) ⇒ Object?

Evaluate a JS expression and return its value (awaits promises).

Extra args are passed to the page as real values, reachable in the expression as arguments[0], arguments[1], ... Without args it's a single Runtime.evaluate (the hot path); with args it goes through Runtime.callFunctionOn so nothing is interpolated into source.

Examples:

frame.evaluate("arguments[0] + arguments[1]", 2, 3)   # => 5

Parameters:

  • expression (String) —

    the JS expression to evaluate.

  • args (Array) —

    values passed to the page as arguments[...].

Returns:

  • (Object, nil) —

    the evaluated value (JSON-decoded).

Raises:



26
27
28
29
30
 
# File 'lib/obxcura/frame/runtime.rb', line 26

def evaluate(expression, *args)
  return handle_result(evaluate_command(expression)) if args.empty?

  evaluate_func("function() { return (#{expression}); }", *args)
end

#evaluate_func(expression, *args, timeout: nil) ⇒ Object?

Call a JS function declaration with the given arguments, bound to the live global object. Unlike #evaluate, expression is the function itself.

Examples:

frame.evaluate_func("function(sel){ return document.querySelector(sel) }", "#id")

Parameters:

  • expression (String) —

    a JS function declaration.

  • args (Array) —

    values passed to the function.

  • timeout (Integer, nil) (defaults to: nil) —

    override for the client's reply timeout.

Returns:

  • (Object, nil) —

    the function's return value (JSON-decoded).

Raises:



42
43
44
 
# File 'lib/obxcura/frame/runtime.rb', line 42

def evaluate_func(expression, *args, timeout: nil)
  call_on(global_object_id, expression, args, timeout: timeout)
end