chrome.debugger
- Description
The
chrome.debuggerAPI serves as an alternate transport for Chrome's remote debugging protocol. Usechrome.debuggerto attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, etc. Use the DebuggeetabIdto target tabs with sendCommand and route events bytabIdfrom onEvent callbacks. - Permissions
Note
For security reasons, the chrome.debugger API does not provide access to all Chrome DevTools Protocol Domains. The available domains are: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio, and WebAuthn.
Manifest
You must declare the `"debugger"`` permission in your extension's manifest to use this API.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}Examples
To try this API, install the debugger API example from the chrome-extension-samples repository.
Summary
- Types
- Methods
- Events
Types
Debuggee
Debuggee identifier. Either tabId or extensionId must be specified
Properties
- extensionId
string optional
The id of the extension which you intend to debug. Attaching to an extension background page is only possible when the
--silent-debugger-extension-apicommand-line switch is used. - tabId
number optional
The id of the tab which you intend to debug.
- targetId
string optional
The opaque id of the debug target.
DetachReason
Connection termination reason.
Enum
"target_closed"
"canceled_by_user"
TargetInfo
Debug target information
Properties
- attached
boolean
True if debugger is already attached.
- extensionId
string optional
The extension id, defined if type = 'background_page'.
- faviconUrl
string optional
Target favicon URL.
- id
string
Target id.
- tabId
number optional
The tab id, defined if type == 'page'.
- title
string
Target page title.
- type
Target type.
- url
string
Target URL.
TargetInfoType
Target type.
Enum
"page"
"background_page"
"worker"
"other"
Methods
attach
chrome.debugger.attach(
target:
Debuggee,
requiredVersion:
string,
callback?:
function,
)
Attaches debugger to the given target.
Parameters
- target
Debugging target to which you want to attach.
- requiredVersion
string
Required debugging protocol version ("0.1"). One can only attach to the debuggee with matching major version and greater or equal minor version. List of the protocol versions can be obtained here.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
detach
chrome.debugger.detach(
target:
Debuggee,
callback?:
function,
)
Detaches debugger from the given target.
Parameters
- target
Debugging target from which you want to detach.
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getTargets
chrome.debugger.getTargets(
callback?:
function,
)
Returns the list of available debug targets.
Parameters
- callback
function optional
The
callbackparameter looks like:(result: TargetInfo[]) => void- result
Array of TargetInfo objects corresponding to the available debug targets.
Returns
Promise<TargetInfo[]>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
sendCommand
chrome.debugger.sendCommand(
target:
Debuggee,
method:
string,
commandParams?:
object,
callback?:
function,
)
Sends given command to the debugging target.
Parameters
- target
Debugging target to which you want to send the command.
- method
string
Method name. Should be one of the methods defined by the remote debugging protocol.
- commandParams
object optional
JSON object with request parameters. This object must conform to the remote debugging params scheme for given method.
- callback
function optional
The
callbackparameter looks like:(result?: object) => void- result
object optional
JSON object with the response. Structure of the response varies depending on the method name and is defined by the 'returns' attribute of the command description in the remote debugging protocol.
Returns
Promise<object | undefined>
Chrome 96+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onDetach
chrome.debugger.onDetach.addListener(
callback:
function,
)
Fired when browser terminates debugging session for the tab. This happens when either the tab is being closed or Chrome DevTools is being invoked for the attached tab.
Parameters
- callback
function
The
callbackparameter looks like:(source: Debuggee, reason: DetachReason) => void- source
- reason
onEvent
chrome.debugger.onEvent.addListener(
callback:
function,
)
Fired whenever debugging target issues instrumentation event.