Google Chrome Extensions

chrome.debugger

Notes

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.

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.

API Reference: chrome.debugger

Types

Debuggee

( object )
Debuggee identifier.

Properties of Debuggee

tabId ( integer )
The id of the tab which you intend to debug.

Methods

attach

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

Attaches debugger to the given target.

Parameters

target ( Debuggee )
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

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

function() {...};

detach

chrome.debugger.detach(Debuggee target)

Detaches debugger from the given target.

Parameters

target ( Debuggee )
Debugging target from which you want to detach.

Callback function

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

function() {...};

sendCommand

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

Sends given command to the debugging target.

Parameters

target ( Debuggee )
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 ( optional object )
JSON object with request parameters. This object must conform to the remote debugging params scheme for given method.

Callback function

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

function(object result) {...};
result ( optional object )
JSON object with the response. Structure of the response varies depending on the method and is defined by the remote debugging protocol.

Events

onEvent

chrome.debugger.onEvent.addListener(function(Debuggee source, string method, object params) {...});

Fired whenever debugging target issues instrumentation event.

Listener Parameters

source ( Debuggee )
The debuggee that generated this event.
method ( string )
Method name. Should be one of the notifications defined by the remote debugging protocol.
params ( optional object )
JSON object with the response. Structure of the response varies depending on the method and is defined by the remote debugging protocol.

onDetach

chrome.debugger.onDetach.addListener(function(Debuggee source) {...});

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.

Listener Parameters

source ( Debuggee )
The debuggee that was detached.

Sample Extensions that use chrome.debugger

  • Live HTTP headers – Displays the live log with the http requests headers
  • JavaScript pause/resume – Pauses / resumes JavaScript execution