説明
chrome.debugger
API は、Chrome のリモート デバッグ プロトコルの代替トランスポートとして機能します。chrome.debugger
を使用して 1 つ以上のタブにアタッチし、ネットワーク インタラクションの測定、JavaScript のデバッグ、DOM と CSS の変更などを行います。Debuggee
プロパティの tabId
を使用して、sendCommand
でタブをターゲットにし、onEvent
コールバックから tabId
でイベントをルーティングします。
権限
debugger
この API を使用するには、拡張機能のマニフェストで "debugger"
権限を宣言する必要があります。
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
コンセプトと使用方法
接続後、chrome.debugger
API を使用すると、Chrome DevTools Protocol(CDP)コマンドを特定のターゲットに送信できます。CDP の詳細については、このドキュメントでは説明しません。CDP の詳細については、公式の CDP ドキュメントをご覧ください。
ターゲット
ターゲットはデバッグ対象を表します。たとえば、タブ、iframe、ワーカーなどがあります。各ターゲットは UUID で識別され、関連するタイプ(iframe
、shared_worker
など)があります。
ターゲット内には、複数の実行コンテキストが存在する場合があります。たとえば、同じプロセス iframe は一意のターゲットを取得せず、単一のターゲットからアクセスできる異なるコンテキストとして表されます。
制限付きドメイン
セキュリティ上の理由から、chrome.debugger
API ではすべての Chrome DevTools プロトコル ドメインにアクセスできるわけではありません。使用できるドメイン: Accessibility、
Audits、CacheStorage、Console、
CSS、Database、Debugger、DOM、
DOMDebugger、DOMSnapshot、DOM20}WebAudioWebAuthn
フレームを操作する
フレームとターゲットの 1 対 1 のマッピングはありません。1 つのタブ内では、複数の同じプロセス フレームが同じターゲットを共有できますが、使用される実行コンテキストは異なります。一方、プロセス外の iframe 用に新しいターゲットが作成されることがあります。
すべてのフレームに取り付けるには、各タイプのフレームを個別に処理する必要があります。
Runtime.executionContextCreated
イベントをリッスンして、同じプロセス フレームに関連付けられている新しい実行コンテキストを特定します。関連するターゲットにアタッチする手順に沿って、プロセス外のフレームを特定します。
関連するターゲットにアタッチ
ターゲットに接続した後、プロセス外の子フレームや関連ワーカーなど、さらに関連するターゲットに接続することもできます。
Chrome 125 以降、chrome.debugger
API はフラット セッションをサポートしています。これにより、メインのデバッガ セッションに子としてターゲットを追加し、chrome.debugger.attach
を再度呼び出すことなく、それらのターゲットにメッセージを送ることができます。代わりに、chrome.debugger.sendCommand
を呼び出すときに sessionId
プロパティを追加して、コマンドを送信する子ターゲットを指定できます。
プロセス外の子フレームに自動的にアタッチするには、まず Target.attachedToTarget
イベントのリスナーを追加します。
chrome.debugger.onEvent.addListener((source, method, params) => {
if (method === "Target.attachedToTarget") {
// `source` identifies the parent session, but we need to construct a new
// identifier for the child session
const session = { ...source, sessionId: params.sessionId };
// Call any needed CDP commands for the child session
await chrome.debugger.sendCommand(session, "Runtime.enable");
}
});
次に、flatten
オプションを true
に設定して Target.setAutoAttach
コマンドを送信し、自動アタッチを有効にします。
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
例
この API を試すには、chrome-extension-samples リポジトリからデバッガ API の例をインストールします。
型
Debuggee
デバッグ対象の識別子。tabId、extensionId、targetId のいずれかを指定する必要があります
プロパティ
-
extensionId
string(省略可)
デバッグする拡張機能の ID。拡張機能の背景ページにアタッチできるのは、
--silent-debugger-extension-api
コマンドライン スイッチが使用されている場合のみです。 -
tabId
number(省略可)
デバッグするタブの ID。
-
targetId
string(省略可)
デバッグ ターゲットの不透明な ID。
DebuggerSession
デバッガ セッション ID。tabId、extensionId、targetId のいずれかを指定する必要があります。また、オプションの sessionId を指定できます。onEvent
から送信された引数に sessionId が指定されている場合、そのイベントはルート デバッグ対象セッション内の子プロトコル セッションから発生したものです。sendCommand
に渡される際に sessionId が指定された場合、ルート デバッグ対象セッション内の子プロトコル セッションをターゲットにします。
プロパティ
-
extensionId
string(省略可)
デバッグする拡張機能の ID。拡張機能の背景ページにアタッチできるのは、
--silent-debugger-extension-api
コマンドライン スイッチが使用されている場合のみです。 -
sessionId
string(省略可)
Chrome DevTools プロトコル セッションの不透明な ID。tabId、extensionId、または targetId によって識別されるルート セッション内の子セッションを識別します。
-
tabId
number(省略可)
デバッグするタブの ID。
-
targetId
string(省略可)
デバッグ ターゲットの不透明な ID。
DetachReason
接続終了の理由。
列挙型
"target_closed"
"canceled_by_user"
TargetInfo
デバッグ ターゲットの情報
プロパティ
-
接続済み
boolean
デバッガがすでにアタッチされている場合は true。
-
extensionId
string(省略可)
type = 'background_page' に定義される拡張機能 ID。
-
faviconUrl
string(省略可)
ターゲットのファビコン URL。
-
id
string
ターゲット ID。
-
tabId
number(省略可)
type == 'page' の場合に定義されるタブ ID。
-
title
string
ターゲット ページのタイトル。
-
type
ターゲット タイプ。
-
url
string
ターゲット URL。
TargetInfoType
ターゲット タイプ。
列挙型
メソッド
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
指定されたターゲットにデバッガをアタッチします。
パラメータ
-
ターゲット
アタッチ先のデバッグ ターゲット。
-
requiredVersion
string
必要なデバッグ プロトコル バージョン(「0.1」)。デバッグ対象には、一致するメジャー バージョンとそれ以降のマイナー バージョンを持つデバッグ対象にのみアタッチできます。プロトコル バージョンのリストはこちらで入手できます。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
指定されたターゲットからデバッガを切断します。
パラメータ
-
ターゲット
接続解除するデバッグ ターゲット。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
使用可能なデバッグ ターゲットのリストを返します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result: TargetInfo[]) => void
-
件の結果
使用可能なデバッグ ターゲットに対応する TargetInfo オブジェクトの配列。
-
戻り値
-
Promise<TargetInfo[]>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
指定されたコマンドをデバッグ ターゲットに送信します。
パラメータ
-
ターゲット
コマンドを送信するデバッグ ターゲット。
-
method
string
メソッド名。リモート デバッグ プロトコルで定義されているメソッドのいずれかにする必要があります。
-
commandParams
オブジェクト 省略可
リクエスト パラメータを含む JSON オブジェクト。このオブジェクトは、指定されたメソッドのリモート デバッグ パラメータ スキームに準拠している必要があります。
-
callback
関数(省略可)
callback
パラメータは次のようになります。(result?: object) => void
-
件の結果
オブジェクト 省略可
JSON オブジェクトを返します。レスポンスの構造はメソッド名によって異なり、リモート デバッグ プロトコルのコマンドの説明の returns 属性で定義されます。
-
戻り値
-
Promise<object | undefined>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
イベント
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
ブラウザがタブのデバッグ セッションを終了したときに呼び出されます。これは、タブを閉じているとき、または接続されたタブに対して Chrome DevTools が呼び出されているときに発生します。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(source: Debuggee, reason: DetachReason) => void
-
source
-
reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
デバッグ ターゲットがインストルメンテーション イベントを発行するたびに呼び出されます。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
string
-
params
オブジェクト 省略可
-