Interface ITarget

Namespace

Selenium.WebDriver.BiDi.Cdp.Target

Assembly

Selenium.WebDriver.BiDi.Cdp.dll

Supports additional targets discovery and allows to attach to them.

public interface ITarget

Properties

AttachedToTarget

Issued when attached to target because of auto-attach or attachToTarget command.

[Experimental("BIDICDP001")]
IEventSource<AttachedToTargetEventArgs> AttachedToTarget { get; }

Property Value

IEventSource<AttachedToTargetEventArgs>

Remarks

Event args (AttachedToTargetEventArgs):

• SessionId - Identifier assigned to the session used to send/receive messages.
• TargetInfo
• WaitingForDebugger

DetachedFromTarget

Issued when detached from target for any reason (including detachFromTarget command). Can be issued multiple times per target if multiple sessions have been attached to it.

[Experimental("BIDICDP001")]
IEventSource<DetachedFromTargetEventArgs> DetachedFromTarget { get; }

Property Value

IEventSource<DetachedFromTargetEventArgs>

Remarks

Event args (DetachedFromTargetEventArgs):

• SessionId - Detached session identifier.
• TargetId - Deprecated.

ReceivedMessageFromTarget

Notifies about a new protocol message received from the session (as reported in attachedToTarget event).

IEventSource<ReceivedMessageFromTargetEventArgs> ReceivedMessageFromTarget { get; }

Property Value

IEventSource<ReceivedMessageFromTargetEventArgs>

Remarks

Event args (ReceivedMessageFromTargetEventArgs):

• SessionId - Identifier of a session which sends a message.
• Message
• TargetId - Deprecated.

TargetCrashed

Issued when a target has crashed.

IEventSource<TargetCrashedEventArgs> TargetCrashed { get; }

Property Value

IEventSource<TargetCrashedEventArgs>

Remarks

Event args (TargetCrashedEventArgs):

• TargetId
• Status - Termination status type.
• ErrorCode - Termination error code.

TargetCreated

Issued when a possible inspection target is created.

IEventSource<TargetCreatedEventArgs> TargetCreated { get; }

Property Value

IEventSource<TargetCreatedEventArgs>

Remarks

Event args (TargetCreatedEventArgs):

• TargetInfo

TargetDestroyed

Issued when a target is destroyed.

IEventSource<TargetDestroyedEventArgs> TargetDestroyed { get; }

Property Value

IEventSource<TargetDestroyedEventArgs>

Remarks

Event args (TargetDestroyedEventArgs):

• TargetId

TargetInfoChanged

Issued when some information about a target has changed. This only happens between targetCreated and targetDestroyed.

IEventSource<TargetInfoChangedEventArgs> TargetInfoChanged { get; }

Property Value

IEventSource<TargetInfoChangedEventArgs>

Remarks

Event args (TargetInfoChangedEventArgs):

• TargetInfo

Methods

ActivateTargetAsync(TargetID, string?, CancellationToken)

Activates (focuses) the target.

Task<ActivateTargetResult> ActivateTargetAsync(TargetID targetId, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<ActivateTargetResult>

A task representing the asynchronous operation, containing a ActivateTargetResult.

AttachToBrowserTargetAsync(string?, CancellationToken)

Attaches to the browser target, only uses flat sessionId mode.

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

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<AttachToBrowserTargetResult>

A task representing the asynchronous operation, containing a AttachToBrowserTargetResult.

AttachToTargetAsync(TargetID, bool?, string?, CancellationToken)

Attaches to the target with given id.

Task<AttachToTargetResult> AttachToTargetAsync(TargetID targetId, bool? flatten = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

flatten bool?

Enables "flat" access to the session via specifying sessionId attribute in the commands. We plan to make this the default, deprecate non-flattened mode, and eventually retire it. See crbug.com/991325.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<AttachToTargetResult>

A task representing the asynchronous operation, containing a AttachToTargetResult.

AutoAttachRelatedAsync(TargetID, bool, ImmutableArray<FilterEntry>?, string?, CancellationToken)

Adds the specified target to the list of targets that will be monitored for any related target creation (such as child frames, child workers and new versions of service worker) and reported through attachedToTarget. The specified target is also auto-attached. This cancels the effect of any previous setAutoAttach and is also cancelled by subsequent setAutoAttach. Only available at the Browser target.

[Experimental("BIDICDP001")]
Task<AutoAttachRelatedResult> AutoAttachRelatedAsync(TargetID targetId, bool waitForDebuggerOnStart, ImmutableArray<FilterEntry>? filter = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

waitForDebuggerOnStart bool

Whether to pause new targets when attaching to them. Use Runtime.runIfWaitingForDebugger to run paused targets.

filter ImmutableArray<FilterEntry>?

Only targets matching filter will be attached.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<AutoAttachRelatedResult>

A task representing the asynchronous operation, containing a AutoAttachRelatedResult.

CloseTargetAsync(TargetID, string?, CancellationToken)

Closes the target. If the target is a page that gets closed too.

Task<CloseTargetResult> CloseTargetAsync(TargetID targetId, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<CloseTargetResult>

A task representing the asynchronous operation, containing a CloseTargetResult.

CreateBrowserContextAsync(bool?, string?, string?, ImmutableArray<string>?, string?, CancellationToken)

Creates a new empty BrowserContext. Similar to an incognito profile but you can have more than one.

Task<CreateBrowserContextResult> CreateBrowserContextAsync(bool? disposeOnDetach = null, string? proxyServer = null, string? proxyBypassList = null, ImmutableArray<string>? originsWithUniversalNetworkAccess = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

disposeOnDetach bool?

If specified, disposes this context when debugging session disconnects.

proxyServer string

Proxy server, similar to the one passed to --proxy-server

proxyBypassList string

Proxy bypass list, similar to the one passed to --proxy-bypass-list

originsWithUniversalNetworkAccess ImmutableArray<string>?

An optional list of origins to grant unlimited cross-origin access to. Parts of the URL other than those constituting origin are ignored.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<CreateBrowserContextResult>

A task representing the asynchronous operation, containing a CreateBrowserContextResult.

CreateTargetAsync(string, long?, long?, long?, long?, WindowState?, BrowserContextID?, bool?, bool?, bool?, bool?, bool?, bool?, string?, CancellationToken)

Creates a new page.

Task<CreateTargetResult> CreateTargetAsync(string url, long? left = null, long? top = null, long? width = null, long? height = null, WindowState? windowState = null, BrowserContextID? browserContextId = null, bool? enableBeginFrameControl = null, bool? newWindow = null, bool? background = null, bool? forTab = null, bool? hidden = null, bool? focus = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

url string

The initial URL the page will be navigated to. An empty string indicates about:blank.

left long?

Frame left origin in DIP (requires newWindow to be true or headless shell).

top long?

Frame top origin in DIP (requires newWindow to be true or headless shell).

width long?

Frame width in DIP (requires newWindow to be true or headless shell).

height long?

Frame height in DIP (requires newWindow to be true or headless shell).

windowState WindowState?

Frame window state (requires newWindow to be true or headless shell). Default is normal.

browserContextId BrowserContextID

The browser context to create the page in.

enableBeginFrameControl bool?

Whether BeginFrames for this target will be controlled via DevTools (headless shell only, not supported on MacOS yet, false by default).

newWindow bool?

Whether to create a new Window or Tab (false by default, not supported by headless shell).

background bool?

Whether to create the target in background or foreground (false by default, not supported by headless shell).

forTab bool?

Whether to create the target of type "tab".

hidden bool?

Whether to create a hidden target. The hidden target is observable via protocol, but not present in the tab UI strip. Cannot be created with forTab: true, newWindow: true or background: false. The life-time of the tab is limited to the life-time of the session.

focus bool?

If specified, determines whether the new target should be focused. By default, the focus behavior depends on the background parameter:

• If background is false (default) and focus is omitted, the new target is focused and the browser window is brought to the foreground.
• If background is false and focus is false, the target is opened but the browser window's focus remains unchanged (e.g., if the window was in the background, it stays there).
• If background is true, setting focus to true is not supported and will result in an error.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<CreateTargetResult>

A task representing the asynchronous operation, containing a CreateTargetResult.

DetachFromTargetAsync(SessionID?, TargetID?, string?, CancellationToken)

Detaches session with given id.

Task<DetachFromTargetResult> DetachFromTargetAsync(SessionID? sessionId = null, TargetID? targetId = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

sessionId SessionID

Session to detach.

targetId TargetID

Deprecated.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<DetachFromTargetResult>

A task representing the asynchronous operation, containing a DetachFromTargetResult.

DisposeBrowserContextAsync(BrowserContextID, string?, CancellationToken)

Deletes a BrowserContext. All the belonging pages will be closed without calling their beforeunload hooks.

Task<DisposeBrowserContextResult> DisposeBrowserContextAsync(BrowserContextID browserContextId, string? session = null, CancellationToken cancellationToken = default)

Parameters

browserContextId BrowserContextID

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<DisposeBrowserContextResult>

A task representing the asynchronous operation, containing a DisposeBrowserContextResult.

ExposeDevToolsProtocolAsync(TargetID, string?, bool?, string?, CancellationToken)

Inject object to the target's main frame that provides a communication channel with browser target.

Injected object will be available as window[bindingName].

The object has the following API:

• binding.send(json) - a method to send messages over the remote debugging protocol
• binding.onmessage = json => handleMessage(json) - a callback that will be called for the protocol notifications and command responses.

[Experimental("BIDICDP001")]
Task<ExposeDevToolsProtocolResult> ExposeDevToolsProtocolAsync(TargetID targetId, string? bindingName = null, bool? inheritPermissions = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

bindingName string

Binding name, 'cdp' if not specified.

inheritPermissions bool?

If true, inherits the current root session's permissions (default: false).

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<ExposeDevToolsProtocolResult>

A task representing the asynchronous operation, containing a ExposeDevToolsProtocolResult.

GetBrowserContextsAsync(string?, CancellationToken)

Returns all browser contexts created with Target.createBrowserContext method.

Task<GetBrowserContextsResult> GetBrowserContextsAsync(string? session = null, CancellationToken cancellationToken = default)

Parameters

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetBrowserContextsResult>

A task representing the asynchronous operation, containing a GetBrowserContextsResult.

GetDevToolsTargetAsync(TargetID, string?, CancellationToken)

Gets the targetId of the DevTools page target opened for the given target (if any).

[Experimental("BIDICDP001")]
Task<GetDevToolsTargetResult> GetDevToolsTargetAsync(TargetID targetId, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

Page or tab target ID.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetDevToolsTargetResult>

A task representing the asynchronous operation, containing a GetDevToolsTargetResult.

GetTargetInfoAsync(TargetID?, string?, CancellationToken)

Returns information about a target.

[Experimental("BIDICDP001")]
Task<GetTargetInfoResult> GetTargetInfoAsync(TargetID? targetId = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetTargetInfoResult>

A task representing the asynchronous operation, containing a GetTargetInfoResult.

GetTargetsAsync(ImmutableArray<FilterEntry>?, string?, CancellationToken)

Retrieves a list of available targets.

Task<GetTargetsResult> GetTargetsAsync(ImmutableArray<FilterEntry>? filter = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

filter ImmutableArray<FilterEntry>?

Only targets matching filter will be reported. If filter is not specified and target discovery is currently enabled, a filter used for target discovery is used for consistency.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<GetTargetsResult>

A task representing the asynchronous operation, containing a GetTargetsResult.

OpenDevToolsAsync(TargetID, string?, string?, CancellationToken)

Opens a DevTools window for the target.

[Experimental("BIDICDP001")]
Task<OpenDevToolsResult> OpenDevToolsAsync(TargetID targetId, string? panelId = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

targetId TargetID

This can be the page or tab target ID.

panelId string

The id of the panel we want DevTools to open initially. Currently supported panels are elements, console, network, sources, resources, timeline, chrome-recorder, heap-profiler, lighthouse, and security.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<OpenDevToolsResult>

A task representing the asynchronous operation, containing a OpenDevToolsResult.

SendMessageToTargetAsync(string, SessionID?, TargetID?, string?, CancellationToken)

Sends protocol message over session with given id. Consider using flat mode instead; see commands attachToTarget, setAutoAttach, and crbug.com/991325.

[Obsolete]
Task<SendMessageToTargetResult> SendMessageToTargetAsync(string message, SessionID? sessionId = null, TargetID? targetId = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

message string

sessionId SessionID

Identifier of the session.

targetId TargetID

Deprecated.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SendMessageToTargetResult>

A task representing the asynchronous operation, containing a SendMessageToTargetResult.

SetAutoAttachAsync(bool, bool, bool?, ImmutableArray<FilterEntry>?, string?, CancellationToken)

Controls whether to automatically attach to new targets which are considered to be directly related to this one (for example, iframes or workers). When turned on, attaches to all existing related targets as well. When turned off, automatically detaches from all currently attached targets. This also clears all targets added by autoAttachRelated from the list of targets to watch for creation of related targets. You might want to call this recursively for auto-attached targets to attach to all available targets.

Task<SetAutoAttachResult> SetAutoAttachAsync(bool autoAttach, bool waitForDebuggerOnStart, bool? flatten = null, ImmutableArray<FilterEntry>? filter = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

autoAttach bool

Whether to auto-attach to related targets.

waitForDebuggerOnStart bool

Whether to pause new targets when attaching to them. Use Runtime.runIfWaitingForDebugger to run paused targets.

flatten bool?

Enables "flat" access to the session via specifying sessionId attribute in the commands. We plan to make this the default, deprecate non-flattened mode, and eventually retire it. See crbug.com/991325.

filter ImmutableArray<FilterEntry>?

Only targets matching filter will be attached.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SetAutoAttachResult>

A task representing the asynchronous operation, containing a SetAutoAttachResult.

SetDiscoverTargetsAsync(bool, ImmutableArray<FilterEntry>?, string?, CancellationToken)

Controls whether to discover available targets and notify via targetCreated/targetInfoChanged/targetDestroyed events.

Task<SetDiscoverTargetsResult> SetDiscoverTargetsAsync(bool discover, ImmutableArray<FilterEntry>? filter = null, string? session = null, CancellationToken cancellationToken = default)

Parameters

discover bool

Whether to discover available targets.

filter ImmutableArray<FilterEntry>?

Only targets matching filter will be attached. If discover is false, filter must be omitted or empty.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SetDiscoverTargetsResult>

A task representing the asynchronous operation, containing a SetDiscoverTargetsResult.

SetRemoteLocationsAsync(ImmutableArray<RemoteLocation>, string?, CancellationToken)

Enables target discovery for the specified locations, when setDiscoverTargets was set to true.

[Experimental("BIDICDP001")]
Task<SetRemoteLocationsResult> SetRemoteLocationsAsync(ImmutableArray<RemoteLocation> locations, string? session = null, CancellationToken cancellationToken = default)

Parameters

locations ImmutableArray<RemoteLocation>

List of remote locations.

session string

Optional CDP session override.

cancellationToken CancellationToken

A token to cancel the asynchronous operation.

Returns

Task<SetRemoteLocationsResult>

A task representing the asynchronous operation, containing a SetRemoteLocationsResult.