Chrome DevTools Protocol

Methods

Target.activateTarget

Activates (focuses) the target.

parameters
targetId
TargetID

Target.attachToTarget

Attaches to the target with given id.

parameters
targetId
TargetID
flatten
boolean

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.

Return Object
sessionId
SessionID

Id assigned to the session.

Target.closeTarget

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

parameters
targetId
TargetID
Return Object
success
boolean

Always set to true. If an error occurs, the response indicates protocol error.

Deprecated

Target.createBrowserContext

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

parameters
disposeOnDetach
boolean

If specified, disposes this context when debugging session disconnects.

Experimental
proxyServer
string

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

Experimental
proxyBypassList
string

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

Experimental
originsWithUniversalNetworkAccess
array[ string ]

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

Experimental
Return Object
browserContextId
Browser.BrowserContextID

The id of the context created.

Target.createTarget

Creates a new page.

parameters
url
string

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

width
integer

Frame width in DIP (headless chrome only).

height
integer

Frame height in DIP (headless chrome only).

browserContextId
Browser.BrowserContextID

The browser context to create the page in.

Experimental
enableBeginFrameControl
boolean

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

Experimental
newWindow
boolean

Whether to create a new Window or Tab (chrome-only, false by default).

background
boolean

Whether to create the target in background or foreground (chrome-only, false by default).

forTab
boolean

Whether to create the target of type "tab".

Experimental
Return Object
targetId
TargetID

The id of the page opened.

Target.detachFromTarget

Detaches session with given id.

parameters
sessionId
SessionID

Session to detach.

targetId
TargetID

Deprecated.

Deprecated

Target.disposeBrowserContext

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

parameters
browserContextId
Browser.BrowserContextID

Target.getBrowserContexts

Returns all browser contexts created with Target.createBrowserContext method.

Return Object
browserContextIds
array[ Browser.BrowserContextID ]

An array of browser context ids.

Target.getTargets

Retrieves a list of available targets.

parameters
filter
TargetFilter

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.

Experimental
Return Object
targetInfos
array[ TargetInfo ]

The list of targets.

Target.setAutoAttach

Controls whether to automatically attach to new targets which are considered to be related to this one. 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.

parameters
autoAttach
boolean

Whether to auto-attach to related targets.

waitForDebuggerOnStart
boolean

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

flatten
boolean

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.

Experimental
filter
TargetFilter

Only targets matching filter will be attached.

Experimental

Target.setDiscoverTargets

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

parameters
discover
boolean

Whether to discover available targets.

filter
TargetFilter

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

Experimental

Target.sendMessageToTarget Deprecated

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

parameters
message
string
sessionId
SessionID

Identifier of the session.

targetId
TargetID

Deprecated.

Deprecated

Target.attachToBrowserTarget Experimental

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

Return Object
sessionId
SessionID

Id assigned to the session.

Target.autoAttachRelated Experimental

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.

parameters
targetId
TargetID
waitForDebuggerOnStart
boolean

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

filter
TargetFilter

Only targets matching filter will be attached.

Experimental

Target.exposeDevToolsProtocol Experimental

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.
parameters
targetId
TargetID
bindingName
string

Binding name, 'cdp' if not specified.

Target.getTargetInfo Experimental

Returns information about a target.

parameters
targetId
TargetID
Return Object
targetInfo
TargetInfo

Target.setRemoteLocations Experimental

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

parameters
locations
array[ RemoteLocation ]

List of remote locations.

Events

Target.receivedMessageFromTarget

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

parameters
sessionId
SessionID

Identifier of a session which sends a message.

message
string
targetId
TargetID

Deprecated.

Deprecated

Target.targetCrashed

Issued when a target has crashed.

parameters
targetId
TargetID
status
string

Termination status type.

errorCode
integer

Termination error code.

Target.targetCreated

Issued when a possible inspection target is created.

parameters
targetInfo
TargetInfo

Target.targetDestroyed

Issued when a target is destroyed.

parameters
targetId
TargetID

Target.targetInfoChanged

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

parameters
targetInfo
TargetInfo

Target.attachedToTarget Experimental

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

parameters
sessionId
SessionID

Identifier assigned to the session used to send/receive messages.

targetInfo
TargetInfo
waitingForDebugger
boolean

Target.detachedFromTarget Experimental

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.

parameters
sessionId
SessionID

Detached session identifier.

targetId
TargetID

Deprecated.

Deprecated

Types

Target.SessionID

Unique identifier of attached debugging session.

Type: string

Target.TargetID

Type: string

Target.TargetInfo

Type: object

properties
targetId
TargetID
type
string

List of types: https://source.chromium.org/chromium/chromium/src/+/main:content/browser/devtools/devtools_agent_host_impl.cc?ss=chromium&q=f:devtools%20-f:out%20%22::kTypeTab%5B%5D%22

title
string
url
string
attached
boolean

Whether the target has an attached client.

openerId
TargetID

Opener target Id

canAccessOpener
boolean

Whether the target has access to the originating window.

Experimental
openerFrameId
Page.FrameId

Frame id of originating window (is only set if target has an opener).

Experimental
browserContextId
Browser.BrowserContextID
Experimental
subtype
string

Provides additional details for specific target types. For example, for the type of "page", this may be set to "portal" or "prerender".

Experimental

Target.FilterEntry Experimental

A filter used by target query/discovery/auto-attach operations.

Type: object

properties
exclude
boolean

If set, causes exclusion of matching targets from the list.

type
string

If not present, matches any type.

Target.RemoteLocation Experimental

Type: object

properties
host
string
port
integer

Target.TargetFilter Experimental

The entries in TargetFilter are matched sequentially against targets and the first entry that matches determines if the target is included or not, depending on the value of exclude field in the entry. If filter is not specified, the one assumed is [{type: "browser", exclude: true}, {type: "tab", exclude: true}, {}] (i.e. include everything but browser and tab).

Type: array