Welcome Getting started API Reference Samples
Welcome Getting started API Reference Samples

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.

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

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 'silent-debugger-extension-api' flag is enabled on the target browser.

  • tabId
    number optional

    The id of the tab which you intend to debug.

  • targetId
    string optional

    The opaque id of the debug target.

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.

  • Target type.

  • url
    string

    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.

  • 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

    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.

  • callback
    function

    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

  • callback
    function

    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.

  • method
    string

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

  • commandParams
    object

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

  • callback
    function

    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) => {...}
    • result
      object

      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

  • listener
    function

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

    (source: Debuggee, reason: DetachReason) => {...}

onEvent

chrome.debugger.onEvent.addListener(listener: function)

Fired whenever debugging target issues instrumentation event.

Event

  • listener
    function

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

    (source: Debuggee, method: string, params: object) => {...}
    • source

      The debuggee that generated this event.

    • method
      string

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

    • params
      object

      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.

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.