Runtime Commands

Runtime commands provide JavaScript execution capabilities and runtime environment management.

Overview

The runtime commands module enables JavaScript code execution, object inspection, and runtime environment control within browser contexts.

pydoll.commands.runtime_commands

RuntimeCommands

A class for interacting with the JavaScript runtime using Chrome DevTools Protocol.

This class provides methods to create commands for evaluating JavaScript expressions, calling functions on JavaScript objects, and retrieving object properties through CDP.

ATTRIBUTE	DESCRIPTION
`EVALUATE_TEMPLATE`	Template for the Runtime.evaluate command. TYPE: `dict`
`CALL_FUNCTION_ON_TEMPLATE`	Template for the Runtime.callFunctionOn command. TYPE: `dict`
`GET_PROPERTIES`	Template for the Runtime.getProperties command. TYPE: `dict`

add_binding `staticmethod`

add_binding(name, execution_context_name=None)

Creates a command to add a JavaScript binding.

PARAMETER	DESCRIPTION
`name`	Name of the binding to add. TYPE: `str`
`execution_context_name`	Name of the execution context to bind to. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to add a JavaScript binding.

await_promise `staticmethod`

await_promise(promise_object_id, return_by_value=None, generate_preview=None)

Creates a command to await a JavaScript promise and return its result.

PARAMETER	DESCRIPTION
`promise_object_id`	ID of the promise to await. TYPE: `str`
`return_by_value`	Whether to return the result by value instead of reference. TYPE: `Optional[bool]` DEFAULT: `None`
`generate_preview`	Whether to generate a preview for the result. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[AwaitPromiseResponse]`	Command[AwaitPromiseResponse]: Command object to await a promise.

call_function_on `staticmethod`

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, throw_on_side_effect=None, unique_context_id=None, serialization_options=None)

Creates a command to call a function with a given declaration on a specific object.

PARAMETER	DESCRIPTION
`function_declaration`	Declaration of the function to call. TYPE: `str`
`object_id`	ID of the object to call the function on. TYPE: `Optional[str]` DEFAULT: `None`
`arguments`	Arguments to pass to the function. TYPE: `Optional[list[CallArgument]]` DEFAULT: `None`
`silent`	Whether to silence exceptions. TYPE: `Optional[bool]` DEFAULT: `None`
`return_by_value`	Whether to return the result by value instead of reference. TYPE: `Optional[bool]` DEFAULT: `None`
`generate_preview`	Whether to generate a preview for the result. TYPE: `Optional[bool]` DEFAULT: `None`
`user_gesture`	Whether to treat the call as initiated by user gesture. TYPE: `Optional[bool]` DEFAULT: `None`
`await_promise`	Whether to await promise result. TYPE: `Optional[bool]` DEFAULT: `None`
`execution_context_id`	ID of the execution context to call the function in. TYPE: `Optional[str]` DEFAULT: `None`
`object_group`	Symbolic group name for the result. TYPE: `Optional[str]` DEFAULT: `None`
`throw_on_side_effect`	Whether to throw if side effect cannot be ruled out. TYPE: `Optional[bool]` DEFAULT: `None`
`unique_context_id`	Unique context ID for the function call. TYPE: `Optional[str]` DEFAULT: `None`
`serialization_options`	Serialization options for the result. TYPE: `Optional[SerializationOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[CallFunctionOnResponse]`	Command[CallFunctionOnResponse]: Command object to call a function on an object.

compile_script `staticmethod`

compile_script(expression, source_url=None, persist_script=None, execution_context_id=None)

Creates a command to compile a JavaScript expression.

PARAMETER	DESCRIPTION
`expression`	JavaScript expression to compile. TYPE: `str`
`source_url`	URL of the source file for the script. TYPE: `Optional[str]` DEFAULT: `None`
`persist_script`	Whether to persist the compiled script. TYPE: `Optional[bool]` DEFAULT: `None`
`execution_context_id`	ID of the execution context to compile the script in. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[CompileScriptResponse]`	Command[CompileScriptResponse]: Command object to compile a script.

disable `staticmethod`

disable()

Disables the runtime domain.

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to disable the runtime domain.

enable `staticmethod`

enable()

Enables the runtime domain.

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to enable the runtime domain.

evaluate `staticmethod`

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, disable_breaks=None, repl_mode=None, allow_unsafe_eval_blocked_by_csp=None, unique_context_id=None, serialization_options=None)

Creates a command to evaluate a JavaScript expression in the global context.

PARAMETER	DESCRIPTION
`expression`	JavaScript expression to evaluate. TYPE: `str`
`object_group`	Symbolic group name for the result. TYPE: `Optional[str]` DEFAULT: `None`
`include_command_line_api`	Whether to include command line API. TYPE: `Optional[bool]` DEFAULT: `None`
`silent`	Whether to silence exceptions. TYPE: `Optional[bool]` DEFAULT: `None`
`context_id`	ID of the execution context to evaluate in. TYPE: `Optional[str]` DEFAULT: `None`
`return_by_value`	Whether to return the result by value instead of reference. TYPE: `Optional[bool]` DEFAULT: `None`
`generate_preview`	Whether to generate a preview for the result. TYPE: `Optional[bool]` DEFAULT: `None`
`user_gesture`	Whether to treat evaluation as initiated by user gesture. TYPE: `Optional[bool]` DEFAULT: `None`
`await_promise`	Whether to await promise result. TYPE: `Optional[bool]` DEFAULT: `None`
`throw_on_side_effect`	Whether to throw if side effect cannot be ruled out. TYPE: `Optional[bool]` DEFAULT: `None`
`timeout`	Timeout in milliseconds. TYPE: `Optional[float]` DEFAULT: `None`
`disable_breaks`	Whether to disable breakpoints during evaluation. TYPE: `Optional[bool]` DEFAULT: `None`
`repl_mode`	Whether to execute in REPL mode. TYPE: `Optional[bool]` DEFAULT: `None`
`allow_unsafe_eval_blocked_by_csp`	Allow unsafe evaluation. TYPE: `Optional[bool]` DEFAULT: `None`
`unique_context_id`	Unique context ID for evaluation. TYPE: `Optional[str]` DEFAULT: `None`
`serialization_options`	Serialization for the result. TYPE: `Optional[SerializationOptions]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[EvaluateResponse]`	Command[EvaluateResponse]: Command object to evaluate JavaScript.

get_properties `staticmethod`

get_properties(object_id, own_properties=None, accessor_properties_only=None, generate_preview=None, non_indexed_properties_only=None)

Creates a command to get properties of a JavaScript object.

PARAMETER	DESCRIPTION
`object_id`	ID of the object to get properties for. TYPE: `str`
`own_properties`	Whether to return only own properties. TYPE: `Optional[bool]` DEFAULT: `None`
`accessor_properties_only`	Whether to return only accessor properties. TYPE: `Optional[bool]` DEFAULT: `None`
`generate_preview`	Whether to generate previews for property values. TYPE: `Optional[bool]` DEFAULT: `None`
`non_indexed_properties_only`	Whether to return only non-indexed properties. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[GetPropertiesResponse]`	Command[GetPropertiesResponse]: Command object to get object properties.

global_lexical_scope_names `staticmethod`

global_lexical_scope_names(execution_context_id=None)

Creates a command to retrieve names of variables from global lexical scope.

PARAMETER	DESCRIPTION
`execution_context_id`	ID of the execution context to get scope names from. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[GlobalLexicalScopeNamesResponse]`	Command[GlobalLexicalScopeNamesResponse]: Command object to get global lexical scope names.

query_objects `staticmethod`

query_objects(prototype_object_id, object_group=None)

Creates a command to query objects with a given prototype.

PARAMETER	DESCRIPTION
`prototype_object_id`	ID of the prototype object. TYPE: `str`
`object_group`	Symbolic group name for the results. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[QueryObjectsResponse]`	Command[QueryObjectsResponse]: Command object to query objects.

release_object `staticmethod`

release_object(object_id)

Creates a command to release a JavaScript object.

PARAMETER	DESCRIPTION
`object_id`	ID of the object to release. TYPE: `str`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to release an object.

release_object_group `staticmethod`

release_object_group(object_group)

Creates a command to release all objects in a group.

PARAMETER	DESCRIPTION
`object_group`	Name of the object group to release. TYPE: `str`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to release an object group.

remove_binding `staticmethod`

remove_binding(name)

Creates a command to remove a JavaScript binding.

PARAMETER	DESCRIPTION
`name`	Name of the binding to remove. TYPE: `str`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to remove a JavaScript binding.

run_script `staticmethod`

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)

Creates a command to run a compiled script.

PARAMETER	DESCRIPTION
`script_id`	ID of the compiled script to run. TYPE: `str`
`execution_context_id`	ID of the execution context to run the script in. TYPE: `Optional[str]` DEFAULT: `None`
`object_group`	Symbolic group name for the result. TYPE: `Optional[str]` DEFAULT: `None`
`silent`	Whether to silence exceptions. TYPE: `Optional[bool]` DEFAULT: `None`
`include_command_line_api`	Whether to include command line API. TYPE: `Optional[bool]` DEFAULT: `None`
`return_by_value`	Whether to return the result by value instead of reference. TYPE: `Optional[bool]` DEFAULT: `None`
`generate_preview`	Whether to generate a preview for the result. TYPE: `Optional[bool]` DEFAULT: `None`
`await_promise`	Whether to await promise result. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command[RunScriptResponse]`	Command[RunScriptResponse]: Command object to run a script.

set_async_call_stack_depth `staticmethod`

set_async_call_stack_depth(max_depth)

Creates a command to set the async call stack depth.

PARAMETER	DESCRIPTION
`max_depth`	Maximum depth of async call stacks. TYPE: `int`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to set async call stack depth.

set_custom_object_formatter_enabled `staticmethod`

set_custom_object_formatter_enabled(enabled)

Creates a command to enable or disable custom object formatters.

PARAMETER	DESCRIPTION
`enabled`	Whether to enable custom object formatters. TYPE: `bool`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to enable/disable custom object formatters.

set_max_call_stack_size_to_capture `staticmethod`

set_max_call_stack_size_to_capture(size)

Creates a command to set the maximum call stack size to capture.

PARAMETER	DESCRIPTION
`size`	Maximum call stack size to capture. TYPE: `int`

RETURNS	DESCRIPTION
`Command[Response]`	Command[Response]: Command object to set max call stack size.

Usage

Runtime commands are used for JavaScript execution and runtime management:

from pydoll.commands.runtime_commands import evaluate, enable
from pydoll.connection.connection_handler import ConnectionHandler

# Enable runtime events
connection = ConnectionHandler()
await enable(connection)

# Execute JavaScript
result = await evaluate(
    connection, 
    expression="document.title",
    return_by_value=True
)
print(result.value)  # Page title

Key Functionality

The runtime commands module provides functions for:

JavaScript Execution

evaluate() - Execute JavaScript expressions
call_function_on() - Call functions on objects
compile_script() - Compile JavaScript for reuse
run_script() - Run compiled scripts

Object Management

get_properties() - Get object properties
release_object() - Release object references
release_object_group() - Release object groups

Runtime Control

enable() / disable() - Enable/disable runtime events
discard_console_entries() - Clear console entries
set_custom_object_formatter_enabled() - Enable custom formatters

Exception Handling

set_async_call_stack_depth() - Set call stack depth
Exception capture and reporting
Error object inspection

Advanced Usage

Complex JavaScript Execution

# Execute complex JavaScript with error handling
script = """
try {
    const elements = document.querySelectorAll('.item');
    return Array.from(elements).map(el => ({
        text: el.textContent,
        href: el.href
    }));
} catch (error) {
    return { error: error.message };
}
"""

result = await evaluate(
    connection,
    expression=script,
    return_by_value=True,
    await_promise=True
)

Object Inspection

# Get detailed object properties
properties = await get_properties(
    connection,
    object_id=object_id,
    own_properties=True,
    accessor_properties_only=False
)

for prop in properties:
    print(f"{prop.name}: {prop.value}")

Console Integration

Runtime commands integrate with browser console: - Console messages and errors - Console API method calls - Custom console formatters

Performance Considerations

JavaScript execution through runtime commands can be slower than native browser execution. Use judiciously for complex operations.

Runtime Commands

Overview

pydoll.commands.runtime_commands

RuntimeCommands

add_binding staticmethod

await_promise staticmethod

call_function_on staticmethod

compile_script staticmethod

disable staticmethod

enable staticmethod

evaluate staticmethod

get_properties staticmethod

global_lexical_scope_names staticmethod

query_objects staticmethod

release_object staticmethod

release_object_group staticmethod

remove_binding staticmethod

run_script staticmethod

set_async_call_stack_depth staticmethod

set_custom_object_formatter_enabled staticmethod

set_max_call_stack_size_to_capture staticmethod