Interface IRuntime

Namespace

Selenium.WebDriver.BiDi.Cdp.Runtime

Assembly

Selenium.WebDriver.BiDi.Cdp.dll

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.

public interface IRuntime

Properties

BindingCalled

Notification is issued every time when binding is called.

[Experimental("BIDICDP001")]
IEventSource<BindingCalledEventArgs> BindingCalled { get; }

Property Value

IEventSource<BindingCalledEventArgs>

Remarks

Event args (BindingCalledEventArgs):

• Name
• Payload
• ExecutionContextId - Identifier of the context where the call was made.

ConsoleAPICalled

Issued when console API was called.

IEventSource<ConsoleAPICalledEventArgs> ConsoleAPICalled { get; }

Property Value

IEventSource<ConsoleAPICalledEventArgs>

Remarks

Event args (ConsoleAPICalledEventArgs):

• Type - Type of the call.
• Args - Call arguments.
• ExecutionContextId - Identifier of the context where the call was made.
• Timestamp - Call timestamp.
• StackTrace - 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.
• Context - 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.

ExceptionRevoked

Issued when unhandled exception was revoked.

IEventSource<ExceptionRevokedEventArgs> ExceptionRevoked { get; }

Property Value

IEventSource<ExceptionRevokedEventArgs>

Remarks

Event args (ExceptionRevokedEventArgs):

• Reason - Reason describing why exception was revoked.
• ExceptionId - The id of revoked exception, as reported in exceptionThrown.

ExceptionThrown

Issued when exception was thrown and unhandled.

IEventSource<ExceptionThrownEventArgs> ExceptionThrown { get; }

Property Value

IEventSource<ExceptionThrownEventArgs>

Remarks

Event args (ExceptionThrownEventArgs):

• Timestamp - Timestamp of the exception.
• ExceptionDetails

ExecutionContextCreated

Issued when new execution context is created.

IEventSource<ExecutionContextCreatedEventArgs> ExecutionContextCreated { get; }

Property Value

IEventSource<ExecutionContextCreatedEventArgs>

Remarks

Event args (ExecutionContextCreatedEventArgs):

• Context - A newly created execution context.

ExecutionContextDestroyed

Issued when execution context is destroyed.

IEventSource<ExecutionContextDestroyedEventArgs> ExecutionContextDestroyed { get; }

Property Value

IEventSource<ExecutionContextDestroyedEventArgs>

Remarks

Event args (ExecutionContextDestroyedEventArgs):

• ExecutionContextId - Id of the destroyed context
• ExecutionContextUniqueId - Unique Id of the destroyed context

ExecutionContextsCleared

Issued when all executionContexts were cleared in browser

IEventSource<ExecutionContextsClearedEventArgs> ExecutionContextsCleared { get; }

Property Value

IEventSource<ExecutionContextsClearedEventArgs>

InspectRequested

Issued when object should be inspected (for example, as a result of inspect() command line API call).

IEventSource<InspectRequestedEventArgs> InspectRequested { get; }

Property Value

IEventSource<InspectRequestedEventArgs>

Remarks

Event args (InspectRequestedEventArgs):

• Object
• Hints
• ExecutionContextId - Identifier of the context where the call was made.

Methods

AddBindingAsync(string, ExecutionContextId?, string?, string?, CancellationToken)

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. 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.

Task<AddBindingResult> AddBindingAsync(string name, ExecutionContextId? executionContextId = null, string? executionContextName = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

name string

executionContextId ExecutionContextId

If specified, the binding would only be exposed to the specified execution context. If omitted and executionContextName is not set, the binding is exposed to all execution contexts of the target. This parameter is mutually exclusive with executionContextName. Deprecated in favor of executionContextName due to an unclear use case and bugs in implementation (crbug.com/1169639). executionContextId will be removed in the future.

executionContextName string

If specified, the binding is exposed to the executionContext with matching name, even for contexts created after the binding is added. See also ExecutionContext.name and worldName parameter to Page.addScriptToEvaluateOnNewDocument. This parameter is mutually exclusive with executionContextId.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<AddBindingResult>

A task representing the asynchronous operation, containing a AddBindingResult.

AwaitPromiseAsync(RemoteObjectId, bool?, bool?, string?, CancellationToken)

Add handler to promise with given promise object id.

Task<AwaitPromiseResult> AwaitPromiseAsync(RemoteObjectId promiseObjectId, bool? returnByValue = null, bool? generatePreview = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

promiseObjectId RemoteObjectId

Identifier of the promise.

returnByValue bool?

Whether the result is expected to be a JSON object that should be sent by value.

generatePreview bool?

Whether preview should be generated for the result.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<AwaitPromiseResult>

A task representing the asynchronous operation, containing a AwaitPromiseResult.

CallFunctionOnAsync(string, RemoteObjectId?, ImmutableArray<CallArgument>?, bool?, bool?, bool?, bool?, bool?, ExecutionContextId?, string?, bool?, string?, SerializationOptions?, string?, CancellationToken)

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

Task<CallFunctionOnResult> CallFunctionOnAsync(string functionDeclaration, RemoteObjectId? objectId = null, ImmutableArray<CallArgument>? arguments = null, bool? silent = null, bool? returnByValue = null, bool? generatePreview = null, bool? userGesture = null, bool? awaitPromise = null, ExecutionContextId? executionContextId = null, string? objectGroup = null, bool? throwOnSideEffect = null, string? uniqueContextId = null, SerializationOptions? serializationOptions = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

functionDeclaration string

Declaration of the function to call.

objectId RemoteObjectId

Identifier of the object to call function on. Either objectId or executionContextId should be specified.

arguments ImmutableArray<CallArgument>?

Call arguments. All call arguments must belong to the same JavaScript world as the target object.

silent bool?

In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.

returnByValue bool?

Whether the result is expected to be a JSON object which should be sent by value. Can be overriden by serializationOptions.

generatePreview bool?

Whether preview should be generated for the result.

userGesture bool?

Whether execution should be treated as initiated by user in the UI.

awaitPromise bool?

Whether execution should await for resulting value and return once awaited promise is resolved.

executionContextId ExecutionContextId

Specifies execution context which global object will be used to call function on. Either executionContextId or objectId should be specified.

objectGroup string

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.

throwOnSideEffect bool?

Whether to throw an exception if side effect cannot be ruled out during evaluation.

uniqueContextId string

An alternative way to specify the execution context to call function on. Compared to contextId that may be reused across processes, this is guaranteed to be system-unique, so it can be used to prevent accidental function call in context different than intended (e.g. as a result of navigation across process boundaries). This is mutually exclusive with executionContextId.

serializationOptions SerializationOptions

Specifies the result serialization. If provided, overrides generatePreview and returnByValue.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<CallFunctionOnResult>

A task representing the asynchronous operation, containing a CallFunctionOnResult.

CompileScriptAsync(string, string, bool, ExecutionContextId?, string?, CancellationToken)

Compiles expression.

Task<CompileScriptResult> CompileScriptAsync(string expression, string sourceURL, bool persistScript, ExecutionContextId? executionContextId = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

expression string

Expression to compile.

sourceURL string

Source url to be set for the script.

persistScript bool

Specifies whether the compiled script should be persisted.

executionContextId ExecutionContextId

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.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<CompileScriptResult>

A task representing the asynchronous operation, containing a CompileScriptResult.

DisableAsync(string?, CancellationToken)

Disables reporting of execution contexts creation.

Task<DisableResult> DisableAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<DisableResult>

A task representing the asynchronous operation, containing a DisableResult.

DiscardConsoleEntriesAsync(string?, CancellationToken)

Discards collected exceptions and console API calls.

Task<DiscardConsoleEntriesResult> DiscardConsoleEntriesAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<DiscardConsoleEntriesResult>

A task representing the asynchronous operation, containing a DiscardConsoleEntriesResult.

EnableAsync(string?, CancellationToken)

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.

Task<EnableResult> EnableAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<EnableResult>

A task representing the asynchronous operation, containing a EnableResult.

EvaluateAsync(string, string?, bool?, bool?, ExecutionContextId?, bool?, bool?, bool?, bool?, bool?, TimeDelta?, bool?, bool?, bool?, string?, SerializationOptions?, string?, CancellationToken)

Evaluates expression on global object.

Task<EvaluateResult> EvaluateAsync(string expression, string? objectGroup = null, bool? includeCommandLineAPI = null, bool? silent = null, ExecutionContextId? contextId = null, bool? returnByValue = null, bool? generatePreview = null, bool? userGesture = null, bool? awaitPromise = null, bool? throwOnSideEffect = null, TimeDelta? timeout = null, bool? disableBreaks = null, bool? replMode = null, bool? allowUnsafeEvalBlockedByCSP = null, string? uniqueContextId = null, SerializationOptions? serializationOptions = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

expression string

Expression to evaluate.

objectGroup string

Symbolic group name that can be used to release multiple objects.

includeCommandLineAPI bool?

Determines whether Command Line API should be available during the evaluation.

silent bool?

In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.

contextId ExecutionContextId

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. This is mutually exclusive with uniqueContextId, which offers an alternative way to identify the execution context that is more reliable in a multi-process environment.

returnByValue bool?

Whether the result is expected to be a JSON object that should be sent by value.

generatePreview bool?

Whether preview should be generated for the result.

userGesture bool?

Whether execution should be treated as initiated by user in the UI.

awaitPromise bool?

Whether execution should await for resulting value and return once awaited promise is resolved.

throwOnSideEffect bool?

Whether to throw an exception if side effect cannot be ruled out during evaluation. This implies disableBreaks below.

timeout TimeDelta

Terminate execution after timing out (number of milliseconds).

disableBreaks bool?

Disable breakpoints during execution.

replMode bool?

Setting this flag to true enables let re-declaration and top-level await. Note that let variables can only be re-declared if they originate from replMode themselves.

allowUnsafeEvalBlockedByCSP bool?

The Content Security Policy (CSP) for the target might block 'unsafe-eval' which includes eval(), Function(), setTimeout() and setInterval() when called with non-callable arguments. This flag bypasses CSP for this evaluation and allows unsafe-eval. Defaults to true.

uniqueContextId string

An alternative way to specify the execution context to evaluate in. Compared to contextId that may be reused across processes, this is guaranteed to be system-unique, so it can be used to prevent accidental evaluation of the expression in context different than intended (e.g. as a result of navigation across process boundaries). This is mutually exclusive with contextId.

serializationOptions SerializationOptions

Specifies the result serialization. If provided, overrides generatePreview and returnByValue.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<EvaluateResult>

A task representing the asynchronous operation, containing a EvaluateResult.

GetExceptionDetailsAsync(RemoteObjectId, string?, CancellationToken)

This method tries to lookup and populate exception details for a JavaScript Error object. Note that the stackTrace portion of the resulting exceptionDetails will only be populated if the Runtime domain was enabled at the time when the Error was thrown.

[Experimental("BIDICDP001")]
Task<GetExceptionDetailsResult> GetExceptionDetailsAsync(RemoteObjectId errorObjectId, string? session = null, CancellationToken cancellationToken = default)

Parameters

errorObjectId RemoteObjectId

The error object for which to resolve the exception details.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetExceptionDetailsResult>

A task representing the asynchronous operation, containing a GetExceptionDetailsResult.

GetHeapUsageAsync(string?, CancellationToken)

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

[Experimental("BIDICDP001")]
Task<GetHeapUsageResult> GetHeapUsageAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetHeapUsageResult>

A task representing the asynchronous operation, containing a GetHeapUsageResult.

GetIsolateIdAsync(string?, CancellationToken)

Returns the isolate id.

[Experimental("BIDICDP001")]
Task<GetIsolateIdResult> GetIsolateIdAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetIsolateIdResult>

A task representing the asynchronous operation, containing a GetIsolateIdResult.

GetPropertiesAsync(RemoteObjectId, bool?, bool?, bool?, bool?, string?, CancellationToken)

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

Task<GetPropertiesResult> GetPropertiesAsync(RemoteObjectId objectId, bool? ownProperties = null, bool? accessorPropertiesOnly = null, bool? generatePreview = null, bool? nonIndexedPropertiesOnly = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

objectId RemoteObjectId

Identifier of the object to return properties for.

ownProperties bool?

If true, returns properties belonging only to the element itself, not to its prototype chain.

accessorPropertiesOnly bool?

If true, returns accessor properties (with getter/setter) only; internal properties are not returned either.

generatePreview bool?

Whether preview should be generated for the results.

nonIndexedPropertiesOnly bool?

If true, returns non-indexed properties only.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetPropertiesResult>

A task representing the asynchronous operation, containing a GetPropertiesResult.

GlobalLexicalScopeNamesAsync(ExecutionContextId?, string?, CancellationToken)

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

Task<GlobalLexicalScopeNamesResult> GlobalLexicalScopeNamesAsync(ExecutionContextId? executionContextId = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

executionContextId ExecutionContextId

Specifies in which execution context to lookup global scope variables.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GlobalLexicalScopeNamesResult>

A task representing the asynchronous operation, containing a GlobalLexicalScopeNamesResult.

QueryObjectsAsync(RemoteObjectId, string?, string?, CancellationToken)

Task<QueryObjectsResult> QueryObjectsAsync(RemoteObjectId prototypeObjectId, string? objectGroup = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

prototypeObjectId RemoteObjectId

Identifier of the prototype to return objects for.

objectGroup string

Symbolic group name that can be used to release the results.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<QueryObjectsResult>

A task representing the asynchronous operation, containing a QueryObjectsResult.

ReleaseObjectAsync(RemoteObjectId, string?, CancellationToken)

Releases remote object with given id.

Task<ReleaseObjectResult> ReleaseObjectAsync(RemoteObjectId objectId, string? session = null, CancellationToken cancellationToken = default)

Parameters

objectId RemoteObjectId

Identifier of the object to release.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<ReleaseObjectResult>

A task representing the asynchronous operation, containing a ReleaseObjectResult.

ReleaseObjectGroupAsync(string, string?, CancellationToken)

Releases all remote objects that belong to a given group.

Task<ReleaseObjectGroupResult> ReleaseObjectGroupAsync(string objectGroup, string? session = null, CancellationToken cancellationToken = default)

Parameters

objectGroup string

Symbolic object group name.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<ReleaseObjectGroupResult>

A task representing the asynchronous operation, containing a ReleaseObjectGroupResult.

RemoveBindingAsync(string, string?, CancellationToken)

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

Task<RemoveBindingResult> RemoveBindingAsync(string name, string? session = null, CancellationToken cancellationToken = default)

Parameters

name string

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<RemoveBindingResult>

A task representing the asynchronous operation, containing a RemoveBindingResult.

RunIfWaitingForDebuggerAsync(string?, CancellationToken)

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

Task<RunIfWaitingForDebuggerResult> RunIfWaitingForDebuggerAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<RunIfWaitingForDebuggerResult>

A task representing the asynchronous operation, containing a RunIfWaitingForDebuggerResult.

RunScriptAsync(ScriptId, ExecutionContextId?, string?, bool?, bool?, bool?, bool?, bool?, string?, CancellationToken)

Runs script with given id in a given context.

Task<RunScriptResult> RunScriptAsync(ScriptId scriptId, ExecutionContextId? executionContextId = null, string? objectGroup = null, bool? silent = null, bool? includeCommandLineAPI = null, bool? returnByValue = null, bool? generatePreview = null, bool? awaitPromise = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

scriptId ScriptId

Id of the script to run.

executionContextId ExecutionContextId

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.

objectGroup string

Symbolic group name that can be used to release multiple objects.

silent bool?

In silent mode exceptions thrown during evaluation are not reported and do not pause execution. Overrides setPauseOnException state.

includeCommandLineAPI bool?

Determines whether Command Line API should be available during the evaluation.

returnByValue bool?

Whether the result is expected to be a JSON object which should be sent by value.

generatePreview bool?

Whether preview should be generated for the result.

awaitPromise bool?

Whether execution should await for resulting value and return once awaited promise is resolved.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<RunScriptResult>

A task representing the asynchronous operation, containing a RunScriptResult.

SetAsyncCallStackDepthAsync(long, string?, CancellationToken)

Enables or disables async call stacks tracking.

Task<SetAsyncCallStackDepthResult> SetAsyncCallStackDepthAsync(long maxDepth, string? session = null, CancellationToken cancellationToken = default)

Parameters

maxDepth long

Maximum depth of async call stacks. Setting to 0 will effectively disable collecting async call stacks (default).

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SetAsyncCallStackDepthResult>

A task representing the asynchronous operation, containing a SetAsyncCallStackDepthResult.

SetCustomObjectFormatterEnabledAsync(bool, string?, CancellationToken)

[Experimental("BIDICDP001")]
Task<SetCustomObjectFormatterEnabledResult> SetCustomObjectFormatterEnabledAsync(bool enabled, string? session = null, CancellationToken cancellationToken = default)

Parameters

enabled bool

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SetCustomObjectFormatterEnabledResult>

A task representing the asynchronous operation, containing a SetCustomObjectFormatterEnabledResult.

SetMaxCallStackSizeToCaptureAsync(long, string?, CancellationToken)

[Experimental("BIDICDP001")]
Task<SetMaxCallStackSizeToCaptureResult> SetMaxCallStackSizeToCaptureAsync(long size, string? session = null, CancellationToken cancellationToken = default)

Parameters

size long

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SetMaxCallStackSizeToCaptureResult>

A task representing the asynchronous operation, containing a SetMaxCallStackSizeToCaptureResult.

TerminateExecutionAsync(string?, CancellationToken)

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

[Experimental("BIDICDP001")]
Task<TerminateExecutionResult> TerminateExecutionAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<TerminateExecutionResult>

A task representing the asynchronous operation, containing a TerminateExecutionResult.