chrome.debugger
- Description
The
chrome.debugger
API serves as an alternate transport for Chrome's remote debugging protocol. Usechrome.debugger
to attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, etc. Use the DebuggeetabId
to target tabs with sendCommand and route events bytabId
from onEvent callbacks.
Notes #
As of today, attaching to the tab by means of the debugger API and using embedded Chrome DevTools with that tab are mutually exclusive. If user invokes Chrome DevTools while extension is attached to the tab, debugging session is terminated. Extension can re-establish it later.
Manifest #
You must declare the "debugger" permission in your extension's manifest to use this API.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Examples #
You can find samples of this API in Samples.
Summary
- Types
- Methods
- Events
Types
Debuggee
Debuggee identifier. Either tabId or extensionId must be specified
Properties
- extensionIdstring optional
The id of the extension which you intend to debug. Attaching to an extension background page is only possible when 'silent-debugger-extension-api' flag is enabled on the target browser.
- tabIdnumber optional
The id of the tab which you intend to debug.
- targetIdstring optional
The opaque id of the debug target.
TargetInfo
Debug target information
Properties
- attachedboolean
True if debugger is already attached.
- extensionIdstring optional
The extension id, defined if type = 'background_page'.
- faviconUrlstring optional
Target favicon URL.
- idstring
Target id.
- tabIdnumber optional
The tab id, defined if type == 'page'.
- titlestring
Target page title.
- type
Target type.
- urlstring
Target URL.
DetachReason
Connection termination reason.
Enum
"target_closed"
, or "canceled_by_user"
TargetInfoType
Target type.
Enum
"page"
, "background_page"
, "worker"
, or "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.
- requiredVersionstring
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.
- callbackfunction
Called once the attach operation succeeds or fails. Callback receives no arguments. If the attach fails,
runtime.lastError
will be set to the error message.The callback parameter should be a function that looks like this:
() => {...}
detach
chrome.debugger.detach(target: Debuggee, callback: function)
Detaches debugger from the given target.
Parameters
- target
Debugging target from which you want to detach.
- callbackfunction
Called once the detach operation succeeds or fails. Callback receives no arguments. If the detach fails,
runtime.lastError
will be set to the error message.The callback parameter should be a function that looks like this:
() => {...}
getTargets
chrome.debugger.getTargets(callback: function)
Returns the list of available debug targets.
Parameters
- callbackfunction
The callback parameter should be a function that looks like this:
(result: TargetInfo[]) => {...}
- result
Array of TargetInfo objects corresponding to the available debug targets.
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.
- methodstring
Method name. Should be one of the methods defined by the remote debugging protocol.
- commandParamsobject
JSON object with request parameters. This object must conform to the remote debugging params scheme for given method.
- callbackfunction
Response body. If an error occurs while posting the message, the callback will be called with no arguments and
runtime.lastError
will be set to the error message.The callback parameter should be a function that looks like this:
(result: object) => {...}
- resultobject
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.
Events
onDetach
chrome.debugger.onDetach.addListener(listener: 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.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(source: Debuggee, reason: DetachReason) => {...}
- source
The debuggee that was detached.
- reason
Connection termination reason.
onEvent
chrome.debugger.onEvent.addListener(listener: function)
Fired whenever debugging target issues instrumentation event.
Event
- listenerfunction
The listener parameter should be a function that looks like this:
(source: Debuggee, method: string, params: object) => {...}
- source
The debuggee that generated this event.
- methodstring
Method name. Should be one of the notifications defined by the remote debugging protocol.
- paramsobject
JSON object with the parameters. Structure of the parameters varies depending on the method name and is defined by the 'parameters' attribute of the event description in the remote debugging protocol.