chrome.debugger

説明

chrome.debugger API は、Chrome の リモート デバッグ プロトコルの代替トランスポートとして機能します。chrome.debugger を使用して 1 つ以上のタブに接続し、ネットワーク インタラクションの計測、JavaScript のデバッグ、DOM と CSS の変更などを行います。Debuggee プロパティ tabId を使用して、sendCommand でタブをターゲットにし、onEvent コールバックから tabId でイベントをルーティングします。

権限

debugger

セキュリティに関する注釈

セキュリティ上の理由から、chrome.debugger API はすべての Chrome DevTools Protocol ドメインへのアクセスを提供しません。使用可能なドメインは、Accessibility、 Audits、CacheStorage、Console、 CSS、Database、Debugger、DOM、 DOMDebugger、DOMSnapshot、 Emulation、Fetch、IO、Input、 Inspector、Log、Network、Overlay、 Page、Performance、Profiler、 Runtime、Storage、Target、Tracing、 WebAudio、WebAuthn です。

マニフェスト

この API を使用するには、拡張機能のマニフェストで "debugger" 権限を宣言する必要があります。

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

例

この API を試すには、デバッガ API のサンプルをchrome-extension-samples リポジトリからインストールします。

型

Debuggee

デバッグ対象の識別子。tabId、extensionId、targetId のいずれかを指定する必要があります

プロパティ

  • extensionId

    文字列（省略可）

    デバッグする拡張機能の ID。拡張機能のバックグラウンド ページへの接続は、--silent-debugger-extension-api コマンドライン スイッチを使用した場合にのみ可能です。

  • tabId

    数値（省略可）

    デバッグするタブの ID。

  • targetId

    文字列（省略可）

    デバッグ対象の不透明な ID。

DebuggerSession

Chrome 125 以降

デバッガ セッション ID。tabId、extensionId、targetId のいずれかを指定する必要があります。また、sessionId を指定することもできます。`onEvent` から送信された引数に sessionId が指定されている場合、イベントはルート デバッグ対象セッション内の子プロトコル セッションから送信されます。`sendCommand` に渡すときに sessionId を指定すると、ルート デバッグ対象セッション内の子プロトコル セッションがターゲットになります。

プロパティ

  • extensionId

    文字列（省略可）

    デバッグする拡張機能の ID。拡張機能のバックグラウンド ページへの接続は、--silent-debugger-extension-api コマンドライン スイッチを使用した場合にのみ可能です。

  • sessionId

    文字列（省略可）

    Chrome DevTools Protocol セッションの不透明な ID。tabId、extensionId、targetId で識別されるルート セッション内の子セッションを識別します。

  • tabId

    数値（省略可）

    デバッグするタブの ID。

  • targetId

    文字列（省略可）

    デバッグ対象の不透明な ID。

DetachReason

Chrome 44 以降

接続終了の理由。

列挙型

"target_closed"

"canceled_by_user"

TargetInfo

デバッグ対象の情報

プロパティ

  • attached

    ブール値

    デバッガがすでに接続されている場合は true。

  • extensionId

    文字列（省略可）

    拡張機能 ID。type = 'background_page' の場合に定義されます。

  • faviconUrl

    文字列（省略可）

    ターゲットのファビコン URL。

  • id

    文字列

    ターゲット ID。

  • tabId

    数値（省略可）

    タブ ID。type == 'page' の場合に定義されます。

  • title

    文字列

    ターゲット ページのタイトル。

  • ターゲット タイプ。

  • url

    文字列

    ターゲット URL。

TargetInfoType

Chrome 44 以降

ターゲット タイプ。

列挙型

"page"

"background_page"

"worker"

"other"

メソッド

attach()

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

指定されたターゲットにデバッガをアタッチします。

パラメータ

  • target

    Debuggee

    アタッチするデバッグ対象。

  • requiredVersion

    文字列

    必要なデバッグ プロトコルのバージョン（「0.1」）。アタッチできるのは、メジャー バージョンが一致し、マイナー バージョンがそれ以上のデバッグ対象のみです。プロトコル バージョンのリストはこちらで確認できます。

  • callback

    関数（省略可）

    callback パラメータは次のようになります: 

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

    アタッチ オペレーションが成功または失敗すると解決されます。Promise は値なしで解決されます。アタッチに失敗すると、Promise は拒否されます。

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

detach()

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

指定されたターゲットからデバッガをデタッチします。

パラメータ

  • target

    Debuggee

    デタッチするデバッグ対象。

  • callback

    関数（省略可）

    callback パラメータは次のようになります: 

    () => void

戻り値

  • Promise<void>

    Chrome 96 以降

    デタッチ オペレーションが成功または失敗すると解決されます。Promise は値なしで解決されます。デタッチに失敗すると、Promise は拒否されます。

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

使用可能なデバッグ対象のリストを返します。

パラメータ

  • callback

    関数（省略可）

    callback パラメータは次のようになります: 

    (result: TargetInfo[]) => void

    • 件の結果

      [TargetInfo][]

      使用可能なデバッグ対象に対応する TargetInfo オブジェクトの配列。

戻り値

  • Promise<TargetInfo[]>

    Chrome 96 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

sendCommand()

Promise 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
): Promise<object | undefined>

指定されたコマンドをデバッグ対象に送信します。

パラメータ

  • コマンドを送信するデバッグ対象。

  • method

    文字列

    メソッド名。リモート デバッグ プロトコルで定義されているメソッドのいずれかである必要があります。

  • commandParams

    オブジェクト（省略可）

    リクエスト パラメータを含む JSON オブジェクト。このオブジェクトは、指定されたメソッドのリモート デバッグ パラメータ スキーマに準拠している必要があります。

  • callback

    関数（省略可）

    callback パラメータは次のようになります: 

    (result?: object) => void

    • 件の結果

      オブジェクト（省略可）

      レスポンスを含む JSON オブジェクト。レスポンスの構造はメソッド名によって異なり、リモート デバッグ プロトコルのコマンド記述の「returns」属性で定義されます。

戻り値

  • Promise<object | undefined>

    Chrome 96 以降

    レスポンスの本文。メッセージの投稿中にエラーが発生すると、Promise は拒否されます。

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onDetach

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

ブラウザがタブのデバッグ セッションを終了したときに発生します。これは、タブが閉じられるか、アタッチされたタブで Chrome DevTools が呼び出された場合に発生します。

パラメータ

onEvent

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

デバッグ対象が計測イベントを発行するたびに発生します。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります: 

    (source: DebuggerSession, method: string, params?: object) => void

    • method

      文字列

    • params

      オブジェクト（省略可）