Extensions
Welcome What's new in Chrome extensions Getting started
Welcome to Manifest V3 Extensions platform vision Overview of Manifest V3 Migrating to Manifest V3 Manifest V3 migration checklist Manifest V2 support timeline
What are extensions? What are themes? Frequently asked questions Extensions quality guidelines FAQ
API Reference Samples
Extension development overview Manifest file format Architecture overview Declare permissions Design the user interface Debugging extensions Samples
Message passing Content scripts Manage events with service workers Match patterns Using promises Cross-origin isolation
Cross-origin XMLHttpRequest Using eval in Chrome extensions
Overriding Chrome settings Extending DevTools OAuth2: Authenticate users with Google Overriding Chrome pages Rich notifications API
Migrating from background pages to service workers
Protect user privacy Declare permissions and warn users Stay secure Accessibility (a11y) Localization message formats Give users options
Extension hosting Alternative extension installation methods Installing extensions on Linux Tutorial: Google analytics
About Manifest V2 Getting started
What are extensions? What are themes? Frequently asked questions
Extension development overview Manifest file format Architecture overview Declare permissions Design the user interface Debugging extensions Samples
Message passing Content scripts Manage events with background scripts Match patterns Cross-origin isolation
Cross-origin XMLHttpRequest Using eval in Chrome extensions
Overriding Chrome settings Extending DevTools OAuth2: Authenticate users with Google Overriding Chrome pages Rich notifications API
Migrate to event-driven background scripts
Protect user privacy Declare permissions and warn users Stay secure Accessibility (a11y) Localization message formats Give users options
Chrome Web Store Alternative extension distribution options Installing extensions on Linux Tutorial: Google analytics

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.

  • 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

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-api command-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

Chrome 44+

Connection termination reason.

Type

"target_closed"

, or

"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.

  • Target type.

  • url

    string

    Target URL.

TargetInfoType

Chrome 44+

Target type.

Type

"page"

,

"background_page"

,

"worker"

, or

"other"

Methods

attach

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

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 optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

detach

chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)
Promise

Detaches debugger from the given target.

Parameters

  • target

    Debuggee

    Debugging target from which you want to detach.

  • callback

    function optional

    The callback parameter looks like: () => void

Returns

  • Promise<void>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

getTargets

chrome.debugger.getTargets(
  callback?: function,
)
Promise

Returns the list of available debug targets.

Parameters

  • callback

    function optional

    The callback parameter looks like: (result: TargetInfo[]) => void

    • result

      TargetInfo[]

      Array of TargetInfo objects corresponding to the available debug targets.

Returns

  • Promise<TargetInfo[]>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to callback.

sendCommand

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

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

    object optional

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

  • callback

    function optional

    The callback parameter 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>

    Pending

    This only returns a Promise when the callback parameter is not specified, and with MV3+. The type inside the Promise is the same as the 1st argument to 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

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

Fired whenever debugging target issues instrumentation event.

Parameters

  • callback

    function

    The callback parameter looks like: (source: Debuggee, method: string, params?: object) => void

    • source

      Debuggee

    • method

      string

    • params

      object optional