chrome.debugger

Description: The chrome.debugger API serves as an alternate transport for Chrome's remote debugging protocol. Use chrome.debugger to attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, etc. Use the Debuggee tabId to target tabs with sendCommand and route events by tabId from onEvent callbacks.
Availability: Since Chrome 35.
Permissions: "debugger"

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
Debuggee
TargetInfoType
DetachReason
TargetInfo
Methods
attach − chrome.debugger.attach( Debuggee target, string requiredVersion, function callback)
detach − chrome.debugger.detach( Debuggee target, function callback)
sendCommand − chrome.debugger.sendCommand( Debuggee target, string method, object commandParams, function callback)
getTargets − chrome.debugger.getTargets(function callback)
Events
onEvent
onDetach

Types

Debuggee

Debuggee identifier. Either tabId or extensionId must be specified
properties
integer (optional) tabId

The id of the tab which you intend to debug.

string (optional) extensionId

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.

string (optional) targetId

The opaque id of the debug target.

TargetInfoType

Target type.
Enum
"page", "background_page", "worker", or "other"

DetachReason

Connection termination reason.
Enum
"target_closed", or "canceled_by_user"

TargetInfo

Debug target information
properties
TargetInfoType type

Target type.

string id

Target id.

integer (optional) tabId

The tab id, defined if type == 'page'.

string (optional) extensionId

The extension id, defined if type = 'background_page'.

boolean attached

True if debugger is already attached.

string title

Target page title.

string url

Target URL.

string (optional) faviconUrl

Target favicon URL.

Methods

attach

chrome.debugger.attach( Debuggee target, string requiredVersion, function callback)

Attaches debugger to the given target.

Parameters
Debuggee target

Debugging target to which you want to attach.

string requiredVersion

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.

function (optional) callback

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.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

detach

chrome.debugger.detach( Debuggee target, function callback)

Detaches debugger from the given target.

Parameters
Debuggee target

Debugging target from which you want to detach.

function (optional) callback

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.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

sendCommand

chrome.debugger.sendCommand( Debuggee target, string method, object commandParams, function callback)

Sends given command to the debugging target.

Parameters
Debuggee target

Debugging target to which you want to send the command.

string method

Method name. Should be one of the methods defined by the remote debugging protocol.

object (optional) commandParams

JSON object with request parameters. This object must conform to the remote debugging params scheme for given method.

function (optional) callback

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.

If you specify the callback parameter, it should be a function that looks like this:

function(object result) {...};
object (optional) result

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.

getTargets

chrome.debugger.getTargets(function callback)

Returns the list of available debug targets.

Parameters
function callback

The callback parameter should be a function that looks like this:

function(array of TargetInfo result) {...};
array of TargetInfo result

Array of TargetInfo objects corresponding to the available debug targets.

Events

onEvent

Fired whenever debugging target issues instrumentation event.

addListener

chrome.debugger.onEvent.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( Debuggee source, string method, object params) {...};
Debuggee source

The debuggee that generated this event.

string method

Method name. Should be one of the notifications defined by the remote debugging protocol.

object (optional) params

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.

onDetach

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.

addListener

chrome.debugger.onDetach.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( Debuggee source, DetachReason reason) {...};
Debuggee source

The debuggee that was detached.

DetachReason reason

Connection termination reason.