Runtime¶

Runtime domain exposes JavaScript runtime by means of remote evaluation and mirror objects. Evaluation results are returned as mirror object that expose object type, string representation and unique identifier that can be used for further object reference. Original objects are maintained in memory unless they are either explicitly released or are released along with the other objects in their object group.

Types
Commands
Events

Types¶

Generally, you do not need to instantiate CDP types yourself. Instead, the API creates objects for you as return values from commands, and then you can use those objects as arguments to other commands.

class cdp.runtime.ScriptId¶: Unique script identifier.

class cdp.runtime.RemoteObjectId¶: Unique object identifier.

class cdp.runtime.UnserializableValue¶: Primitive value which cannot be JSON-stringified. Includes values -0, NaN, Infinity, -Infinity, and bigint literals.

class cdp.runtime.RemoteObject(type_, subtype=None, class_name=None, value=None, unserializable_value=None, description=None, object_id=None, preview=None, custom_preview=None)¶

Mirror object referencing original JavaScript object.

class_name = None¶: Object class (constructor) name. Specified for object type values only.

custom_preview = None¶

description = None¶: String representation of the object.

object_id = None¶: Unique object identifier (for non-primitive values).

preview = None¶: Preview containing abbreviated property values. Specified for object type values only.

subtype = None¶: Object subtype hint. Specified for object type values only.

type_ = None¶: Object type.

unserializable_value = None¶: Primitive value which can not be JSON-stringified does not have value, but gets this property.

value = None¶: Remote object value in case of primitive values or JSON values (if it was requested).

class cdp.runtime.CustomPreview(header, body_getter_id=None)¶

body_getter_id = None¶: If formatter returns true as a result of formatter.hasBody call then bodyGetterId will contain RemoteObjectId for the function that returns result of formatter.body(object, config) call. The result value is json ML array.

header = None¶: The JSON-stringified result of formatter.header(object, config) call. It contains json ML array that represents RemoteObject.

class cdp.runtime.ObjectPreview(type_, overflow, properties, subtype=None, description=None, entries=None)¶

Object containing abbreviated remote object value.

description = None¶: String representation of the object.

entries = None¶: List of the entries. Specified for map and set subtype values only.

overflow = None¶: True iff some of the properties or entries of the original object did not fit.

properties = None¶: List of the properties.

subtype = None¶: Object subtype hint. Specified for object type values only.

type_ = None¶: Object type.

class cdp.runtime.PropertyPreview(name, type_, value=None, value_preview=None, subtype=None)¶

name = None¶: Property name.

subtype = None¶: Object subtype hint. Specified for object type values only.

type_ = None¶: Object type. Accessor means that the property itself is an accessor property.

value = None¶: User-friendly property value string.

value_preview = None¶: Nested value preview.

class cdp.runtime.EntryPreview(value, key=None)¶

key = None¶: Preview of the key. Specified for map-like collection entries.

value = None¶: Preview of the value.

class cdp.runtime.PropertyDescriptor(name, configurable, enumerable, value=None, writable=None, get=None, set_=None, was_thrown=None, is_own=None, symbol=None)¶

Object property descriptor.

configurable = None¶: True if the type of this property descriptor may be changed and if the property may be deleted from the corresponding object.

enumerable = None¶: True if this property shows up during enumeration of the properties on the corresponding object.

get = None¶: A function which serves as a getter for the property, or undefined if there is no getter (accessor descriptors only).

is_own = None¶: True if the property is owned for the object.

name = None¶: Property name or symbol description.

set_ = None¶: A function which serves as a setter for the property, or undefined if there is no setter (accessor descriptors only).

symbol = None¶: Property symbol object, if the property is of the symbol type.

value = None¶: The value associated with the property.

was_thrown = None¶: True if the result was thrown during the evaluation.

writable = None¶: True if the value associated with the property may be changed (data descriptors only).

class cdp.runtime.InternalPropertyDescriptor(name, value=None)¶

Object internal property descriptor. This property isn’t normally visible in JavaScript code.

name = None¶: Conventional property name.

value = None¶: The value associated with the property.

class cdp.runtime.PrivatePropertyDescriptor(name, value)¶

Object private field descriptor.

name = None¶: Private property name.

value = None¶: The value associated with the private property.

class cdp.runtime.CallArgument(value=None, unserializable_value=None, object_id=None)¶

Represents function call argument. Either remote object id objectId, primitive value, unserializable primitive value or neither of (for undefined) them should be specified.

object_id = None¶: Remote object handle.

unserializable_value = None¶: Primitive value which can not be JSON-stringified.

value = None¶: Primitive value or serializable javascript object.

class cdp.runtime.ExecutionContextId¶: Id of an execution context.

class cdp.runtime.ExecutionContextDescription(id_, origin, name, aux_data=None)¶

Description of an isolated world.

aux_data = None¶: Embedder-specific auxiliary data.

id_ = None¶: Unique id of the execution context. It can be used to specify in which execution context script evaluation should be performed.

name = None¶: Human readable name describing given context.

origin = None¶: Execution context origin.

class cdp.runtime.ExceptionDetails(exception_id, text, line_number, column_number, script_id=None, url=None, stack_trace=None, exception=None, execution_context_id=None)¶

Detailed information about exception (or error) that was thrown during script compilation or execution.

column_number = None¶: Column number of the exception location (0-based).

exception = None¶: Exception object if available.

exception_id = None¶: Exception id.

execution_context_id = None¶: Identifier of the context where exception happened.

line_number = None¶: Line number of the exception location (0-based).

script_id = None¶: Script ID of the exception location.

stack_trace = None¶: JavaScript stack trace if available.

text = None¶: Exception text, which should be used together with exception object when available.

url = None¶: URL of the exception location, to be used when the script was not reported.

class cdp.runtime.Timestamp¶: Number of milliseconds since epoch.

class cdp.runtime.TimeDelta¶: Number of milliseconds.

class cdp.runtime.CallFrame(function_name, script_id, url, line_number, column_number)¶

Stack entry for runtime errors and assertions.

column_number = None¶: JavaScript script column number (0-based).

function_name = None¶: JavaScript function name.

line_number = None¶: JavaScript script line number (0-based).

script_id = None¶: JavaScript script id.

url = None¶: JavaScript script name or url.

class cdp.runtime.StackTrace(call_frames, description=None, parent=None, parent_id=None)¶

Call frames for assertions or error messages.

call_frames = None¶: JavaScript function name.

description = None¶: String label of this stack trace. For async traces this may be a name of the function that initiated the async call.

parent = None¶: Asynchronous JavaScript stack trace that preceded this stack, if available.

parent_id = None¶: Asynchronous JavaScript stack trace that preceded this stack, if available.

class cdp.runtime.UniqueDebuggerId¶: Unique identifier of current debugger.

class cdp.runtime.StackTraceId(id_, debugger_id=None)¶

If debuggerId is set stack trace comes from another debugger and can be resolved there. This allows to track cross-debugger calls. See Runtime.StackTrace and Debugger.paused for usages.

debugger_id = None¶

Commands¶

Each command is a generator function. The return type Generator[x, y, z] indicates that the generator yields arguments of type x, it must be resumed with an argument of type y, and it returns type z. In this library, types x and y are the same for all commands, and z is the return type you should pay attention to. For more information, see Getting Started: Commands.

cdp.runtime.add_binding(name, execution_context_id=None)¶

If executionContextId is empty, adds binding with the given name on the global objects of all inspected contexts, including those created later, bindings survive reloads. If executionContextId is specified, adds binding only on global object of given execution context. Binding function takes exactly one argument, this argument should be string, in case of any other input, function throws an exception. Each binding function call produces Runtime.bindingCalled notification.

EXPERIMENTAL

Parameters:	name (`str`) – execution_context_id (`Optional`[`ExecutionContextId`]) – (Optional)
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.await_promise(promise_object_id, return_by_value=None, generate_preview=None)¶

Add handler to promise with given promise object id.

Parameters:

promise_object_id (RemoteObjectId) – Identifier of the promise.
return_by_value (Optional[bool]) – (Optional) Whether the result is expected to be a JSON object that should be sent by value.
generate_preview (Optional[bool]) – (Optional) Whether preview should be generated for the result.

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[RemoteObject, Optional[ExceptionDetails]]]

Returns:

A tuple with the following items:

result - Promise result. Will contain rejected value if promise was rejected.
exceptionDetails - (Optional) Exception details if stack strace is available.

cdp.runtime.call_function_on(function_declaration, object_id=None, arguments=None, silent=None, return_by_value=None, generate_preview=None, user_gesture=None, await_promise=None, execution_context_id=None, object_group=None)¶

Calls function with given declaration on the given object. Object group of the result is inherited from the target object.

Parameters:

function_declaration (str) – Declaration of the function to call.
object_id (Optional[RemoteObjectId]) – (Optional) Identifier of the object to call function on. Either objectId or executionContextId should be specified.
arguments (Optional[List[CallArgument]]) – (Optional) Call arguments. All call arguments must belong to the same JavaScript world as the target object.
silent (Optional[bool]) – (Optional) In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides `setPauseOnException`` state.
return_by_value (Optional[bool]) – (Optional) Whether the result is expected to be a JSON object which should be sent by value.
generate_preview (Optional[bool]) – (EXPERIMENTAL) (Optional) Whether preview should be generated for the result.
user_gesture (Optional[bool]) – (Optional) Whether execution should be treated as initiated by user in the UI.
await_promise (Optional[bool]) – (Optional) Whether execution should ``await` for resulting value and return once awaited promise is resolved.
execution_context_id (Optional[ExecutionContextId]) – (Optional) Specifies execution context which global object will be used to call function on. Either executionContextId or objectId should be specified.
object_group (Optional[str]) – (Optional) Symbolic group name that can be used to release multiple objects. If objectGroup is not specified and objectId is, objectGroup will be inherited from object.

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[RemoteObject, Optional[ExceptionDetails]]]

Returns:

A tuple with the following items:

result - Call result.
exceptionDetails - (Optional) Exception details.

cdp.runtime.compile_script(expression, source_url, persist_script, execution_context_id=None)¶

Compiles expression.

Parameters:

expression (str) – Expression to compile.
source_url (str) – Source url to be set for the script.
persist_script (bool) – Specifies whether the compiled script should be persisted.
execution_context_id (Optional[ExecutionContextId]) – (Optional) Specifies in which execution context to perform script run. If the parameter is omitted the evaluation will be performed in the context of the inspected page.

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[Optional[ScriptId], Optional[ExceptionDetails]]]

Returns:

A tuple with the following items:

scriptId - (Optional) Id of the script.
exceptionDetails - (Optional) Exception details.

cdp.runtime.disable()¶

Disables reporting of execution contexts creation.

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.discard_console_entries()¶

Discards collected exceptions and console API calls.

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.enable()¶

Enables reporting of execution contexts creation by means of executionContextCreated event. When the reporting gets enabled the event will be sent immediately for each existing execution context.

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.evaluate(expression, object_group=None, include_command_line_api=None, silent=None, context_id=None, return_by_value=None, generate_preview=None, user_gesture=None, await_promise=None, throw_on_side_effect=None, timeout=None)¶

Evaluates expression on global object.

Parameters:

expression (str) – Expression to evaluate.
object_group (Optional[str]) – (Optional) Symbolic group name that can be used to release multiple objects.
include_command_line_api (Optional[bool]) – (Optional) Determines whether Command Line API should be available during the evaluation.
silent (Optional[bool]) – (Optional) In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides `setPauseOnException`` state.
context_id (Optional[ExecutionContextId]) – (Optional) Specifies in which execution context to perform evaluation. If the parameter is omitted the evaluation will be performed in the context of the inspected page.
return_by_value (Optional[bool]) – (Optional) Whether the result is expected to be a JSON object that should be sent by value.
generate_preview (Optional[bool]) – (EXPERIMENTAL) (Optional) Whether preview should be generated for the result.
user_gesture (Optional[bool]) – (Optional) Whether execution should be treated as initiated by user in the UI.
await_promise (Optional[bool]) – (Optional) Whether execution should ``await` for resulting value and return once awaited promise is resolved.
throw_on_side_effect (Optional[bool]) – (EXPERIMENTAL) (Optional) Whether to throw an exception if side effect cannot be ruled out during evaluation.
timeout (Optional[TimeDelta]) – (EXPERIMENTAL) (Optional) Terminate execution after timing out (number of milliseconds).

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[RemoteObject, Optional[ExceptionDetails]]]

Returns:

A tuple with the following items:

result - Evaluation result.
exceptionDetails - (Optional) Exception details.

cdp.runtime.get_heap_usage()¶

Returns the JavaScript heap usage. It is the total usage of the corresponding isolate not scoped to a particular Runtime.

EXPERIMENTAL

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `Tuple`[`float`, `float`]]
Returns:	A tuple with the following items: usedSize - Used heap size in bytes. totalSize - Allocated heap size in bytes.

cdp.runtime.get_isolate_id()¶

Returns the isolate id.

EXPERIMENTAL

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `str`]
Returns:	The isolate id.

cdp.runtime.get_properties(object_id, own_properties=None, accessor_properties_only=None, generate_preview=None)¶

Returns properties of a given object. Object group of the result is inherited from the target object.

Parameters:

object_id (RemoteObjectId) – Identifier of the object to return properties for.
own_properties (Optional[bool]) – (Optional) If true, returns properties belonging only to the element itself, not to its prototype chain.
accessor_properties_only (Optional[bool]) – (EXPERIMENTAL) (Optional) If true, returns accessor properties (with getter/setter) only; internal properties are not returned either.
generate_preview (Optional[bool]) – (EXPERIMENTAL) (Optional) Whether preview should be generated for the results.

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[List[PropertyDescriptor], Optional[List[InternalPropertyDescriptor]], Optional[List[PrivatePropertyDescriptor]], Optional[ExceptionDetails]]]

Returns:

A tuple with the following items:

result - Object properties.
internalProperties - (Optional) Internal object properties (only of the element itself).
privateProperties - (Optional) Object private properties.
exceptionDetails - (Optional) Exception details.

cdp.runtime.global_lexical_scope_names(execution_context_id=None)¶

Returns all let, const and class variables from global scope.

Parameters:	execution_context_id (`Optional`[`ExecutionContextId`]) – (Optional) Specifies in which execution context to lookup global scope variables.
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `List`[`str`]]
Returns:

cdp.runtime.query_objects(prototype_object_id, object_group=None)¶

Parameters:	prototype_object_id (`RemoteObjectId`) – Identifier of the prototype to return objects for. object_group (`Optional`[`str`]) – (Optional) Symbolic group name that can be used to release the results.
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `RemoteObject`]
Returns:	Array with objects.

cdp.runtime.release_object(object_id)¶

Releases remote object with given id.

Parameters:	object_id (`RemoteObjectId`) – Identifier of the object to release.
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.release_object_group(object_group)¶

Releases all remote objects that belong to a given group.

Parameters:	object_group (`str`) – Symbolic object group name.
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.remove_binding(name)¶

This method does not remove binding function from global object but unsubscribes current runtime agent from Runtime.bindingCalled notifications.

EXPERIMENTAL

Parameters:	name (`str`) –
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.run_if_waiting_for_debugger()¶

Tells inspected instance to run if it was waiting for debugger to attach.

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.run_script(script_id, execution_context_id=None, object_group=None, silent=None, include_command_line_api=None, return_by_value=None, generate_preview=None, await_promise=None)¶

Runs script with given id in a given context.

Parameters:

script_id (ScriptId) – Id of the script to run.
execution_context_id (Optional[ExecutionContextId]) – (Optional) Specifies in which execution context to perform script run. If the parameter is omitted the evaluation will be performed in the context of the inspected page.
object_group (Optional[str]) – (Optional) Symbolic group name that can be used to release multiple objects.
silent (Optional[bool]) – (Optional) In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides `setPauseOnException`` state.
include_command_line_api (Optional[bool]) – (Optional) Determines whether Command Line API should be available during the evaluation.
return_by_value (Optional[bool]) – (Optional) Whether the result is expected to be a JSON object which should be sent by value.
generate_preview (Optional[bool]) – (Optional) Whether preview should be generated for the result.
await_promise (Optional[bool]) – (Optional) Whether execution should ``await` for resulting value and return once awaited promise is resolved.

Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[RemoteObject, Optional[ExceptionDetails]]]

Returns:

A tuple with the following items:

result - Run result.
exceptionDetails - (Optional) Exception details.

cdp.runtime.set_async_call_stack_depth(max_depth)¶

Enables or disables async call stacks tracking.

Parameters:	max_depth (`int`) – Maximum depth of async call stacks. Setting to `0` will effectively disable collecting async call stacks (default).
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.set_custom_object_formatter_enabled(enabled)¶

EXPERIMENTAL

Parameters:	enabled (`bool`) –
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.set_max_call_stack_size_to_capture(size)¶

EXPERIMENTAL

Parameters:	size (`int`) –
Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

cdp.runtime.terminate_execution()¶

Terminate current or next JavaScript execution. Will cancel the termination when the outer-most script execution ends.

EXPERIMENTAL

Return type:	`Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

Events¶

Generally, you do not need to instantiate CDP events yourself. Instead, the API creates events for you and then you use the event’s attributes.

class cdp.runtime.BindingCalled(name, payload, execution_context_id)¶

EXPERIMENTAL

Notification is issued every time when binding is called.

execution_context_id = None¶: Identifier of the context where the call was made.

class cdp.runtime.ConsoleAPICalled(type_, args, execution_context_id, timestamp, stack_trace, context)¶

Issued when console API was called.

args = None¶: Call arguments.

context = None¶: Console context descriptor for calls on non-default console context (not console.*): ‘anonymous#unique-logger-id’ for call on unnamed context, ‘name#unique-logger-id’ for call on named context.

execution_context_id = None¶: Identifier of the context where the call was made.

stack_trace = None¶: Stack trace captured when the call was made. The async stack chain is automatically reported for the following call types: assert, error, trace, warning. For other types the async call chain can be retrieved using Debugger.getStackTrace and stackTrace.parentId field.

timestamp = None¶: Call timestamp.

type_ = None¶: Type of the call.

class cdp.runtime.ExceptionRevoked(reason, exception_id)¶

Issued when unhandled exception was revoked.

exception_id = None¶: The id of revoked exception, as reported in exceptionThrown.

reason = None¶: Reason describing why exception was revoked.

class cdp.runtime.ExceptionThrown(timestamp, exception_details)¶

Issued when exception was thrown and unhandled.

timestamp = None¶: Timestamp of the exception.

class cdp.runtime.ExecutionContextCreated(context)¶

Issued when new execution context is created.

context = None¶: A newly created execution context.

class cdp.runtime.ExecutionContextDestroyed(execution_context_id)¶

Issued when execution context is destroyed.

execution_context_id = None¶: Id of the destroyed context

class cdp.runtime.ExecutionContextsCleared¶: Issued when all executionContexts were cleared in browser

class cdp.runtime.InspectRequested(object_, hints)¶: Issued when object should be inspected (for example, as a result of inspect() command line API call).