chrome.debugger

Deskripsi

chrome.debugger API berfungsi sebagai transpor alternatif untuk protokol proses debug jarak jauh Chrome. Gunakan chrome.debugger untuk melampirkan ke satu atau beberapa tab untuk menginstrumentasikan interaksi jaringan, men-debug JavaScript, mengubah DOM dan CSS, dan lainnya. Gunakan properti Debuggee tabId untuk menargetkan tab dengan sendCommand dan merutekan peristiwa paling lambat tabId dari callback onEvent.

Izin

debugger

Anda harus mendeklarasikan izin "debugger" dalam manifes ekstensi Anda untuk menggunakan API ini.

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

Konsep dan penggunaan

Setelah terpasang, chrome.debugger API akan memungkinkan Anda mengirim Protokol Chrome DevTools (CDP) ke target tertentu. Menjelaskan CDP secara mendalam di luar cakupan untuk dokumentasi ini—untuk mempelajari CDP lebih lanjut, lihat dokumentasi CDP resmi.

Target

Target mewakili sesuatu yang sedang di-debug—ini dapat mencakup tab, iframe atau pekerja. Setiap target diidentifikasi oleh UUID dan memiliki (seperti iframe, shared_worker, dan lainnya).

Dalam target, mungkin terdapat beberapa konteks eksekusi—misalnya iframe proses tidak mendapatkan target unik, melainkan ditampilkan sebagai berbagai konteks yang dapat diakses dari satu target.

Domain yang dibatasi

Untuk alasan keamanan, chrome.debugger API tidak menyediakan akses ke semua Chrome DevTools Domain Protokol. Domain yang tersedia adalah: Accessibility, Audit, CacheStorage, Konsol, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulasi, Pengambilan, IO, Input, Inspektur, Log, Jaringan, Overlay, Halaman, Performa, Profiler, Runtime, Penyimpanan, Target, Pelacakan, WebAudio, dan WebAuthn.

Menangani frame

Tidak ada pemetaan frame ke target satu ke target. Dalam satu tab, beberapa {i>frame<i} proses yang sama dapat berbagi target yang sama tetapi menggunakan konteks eksekusi. Di sisi lain, target baru mungkin dibuat untuk iframe di luar proses.

Untuk memasang ke semua frame, Anda harus menangani setiap jenis frame secara terpisah:

  • Proses peristiwa Runtime.executionContextCreated untuk mengidentifikasi peristiwa konteks eksekusi yang terkait dengan frame proses yang sama.

  • Ikuti langkah-langkah untuk dilampirkan ke target terkait untuk mengidentifikasi {i>frame<i} di luar proses.

Setelah terhubung ke target, Anda mungkin ingin terhubung ke target terkait lainnya termasuk frame turunan di luar proses atau pekerja terkait.

Mulai Chrome 125, chrome.debugger API mendukung sesi datar. Ini memungkinkan Anda menambahkan target sebagai turunan ke sesi debugger utama dan kirim pesan kepada mereka tanpa perlu panggilan lain ke chrome.debugger.attach. Sebagai gantinya, Anda dapat menambahkan properti sessionId saat memanggil chrome.debugger.sendCommand ke identifikasi target turunan yang ingin Anda kirimi perintah.

Untuk secara otomatis memasang di luar {i>frame<i} turunan dalam proses, pertama-tama tambahkan sebuah pemroses untuk peristiwa 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");
  }
});

Kemudian, aktifkan auto Attach dengan mengirimkan perintah Target.setAutoAttach bersama opsi flatten ditetapkan ke true:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Contoh

Untuk mencoba API ini, instal contoh API debugger dari chrome-extension-samples repositori resource.

Jenis

Debuggee

ID debug. TabId, extensionId, atau targetId harus ditentukan

Properti

  • extensionId

    string opsional

    ID ekstensi yang ingin Anda debug. Pemasangan ke halaman latar belakang ekstensi hanya dapat dilakukan jika tombol command line --silent-debugger-extension-api digunakan.

  • tabId

    angka opsional

    ID tab yang ingin Anda debug.

  • targetId

    string opsional

    ID buram target debug.

DebuggerSession

Chrome 125 dan yang lebih baru

ID sesi debugger. Salah satu dari tabId, extensionId, atau targetId harus ditentukan. Selain itu, sessionId opsional dapat diberikan. Jika sessionId ditentukan untuk argumen yang dikirim dari onEvent, artinya peristiwa tersebut berasal dari sesi protokol turunan dalam sesi debuggee root. Jika sessionId ditentukan saat diteruskan ke sendCommand, sesi tersebut akan menargetkan sesi protokol turunan dalam sesi debuggee root.

Properti

  • extensionId

    string opsional

    ID ekstensi yang ingin Anda debug. Pemasangan ke halaman latar belakang ekstensi hanya dapat dilakukan jika tombol command line --silent-debugger-extension-api digunakan.

  • sessionId

    string opsional

    ID buram sesi Chrome DevTools Protocol. Mengidentifikasi sesi turunan dalam sesi root yang diidentifikasi oleh tabId, extensionId, atau targetId.

  • tabId

    angka opsional

    ID tab yang ingin Anda debug.

  • targetId

    string opsional

    ID buram target debug.

DetachReason

Chrome 44 dan yang lebih baru

Alasan penghentian koneksi.

Enum

"target_closed"

&quot;canceled_by_user&quot;

TargetInfo

Informasi target debug

Properti

  • terpasang

    boolean

    True jika debugger sudah terpasang.

  • extensionId

    string opsional

    ID ekstensi, ditentukan jika jenis = 'background_page'.

  • faviconUrl

    string opsional

    URL favicon target.

  • id

    string

    ID target.

  • tabId

    angka opsional

    ID tab, ditentukan jika jenis == 'halaman'.

  • judul

    string

    Judul halaman target.

  • Jenis target.

  • url

    string

    URL Target.

TargetInfoType

Chrome 44 dan yang lebih baru

Jenis target.

Enum

"halaman"

&quot;background_page&quot;

"pekerja"

"lainnya"

Metode

attach()

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

Memasang debugger ke target yang ditentukan.

Parameter

  • target

    Debugge

    Men-debug target yang ingin Anda lampirkan.

  • requiredVersion

    string

    Versi protokol proses debug yang diperlukan ("0.1"). Anda hanya dapat melampirkan ke debuggee dengan versi utama yang cocok dan versi minor yang lebih besar atau yang sama. Daftar versi protokol dapat diperoleh di sini.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

detach()

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

Melepaskan debugger dari target yang ditentukan.

Parameter

  • target

    Debugge

    Men-debug target yang ingin Anda lepaskan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<void>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getTargets()

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

Menampilkan daftar target debug yang tersedia.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (result: TargetInfo[]) => void

    • hasil

      TargetInfo[]

      Array objek TargetInfo yang sesuai dengan target debug yang tersedia.

Hasil

  • Promise&lt;TargetInfo[]&gt;

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

sendCommand()

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

Mengirim perintah yang diberikan ke target proses debug.

Parameter

  • Men-debug target yang menjadi tujuan pengiriman perintah Anda.

  • method

    string

    Nama metode. Harus berupa salah satu metode yang ditentukan oleh protokol proses debug jarak jauh.

  • commandParams

    objek opsional

    Objek JSON dengan parameter permintaan. Objek ini harus sesuai dengan skema parameter proses debug jarak jauh untuk metode yang ditentukan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (result?: object) => void

    • hasil

      objek opsional

      objek JSON dengan respons. Struktur respons bervariasi bergantung pada nama metode dan ditentukan oleh 'returns' dari deskripsi perintah dalam protokol proses debug jarak jauh.

Hasil

  • Promise&lt;object | tidak terdefinisi>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onDetach

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

Diaktifkan saat browser menghentikan sesi proses debug untuk tab tersebut. Hal ini terjadi saat tab ditutup atau Chrome DevTools dipanggil untuk tab yang terpasang.

Parameter

onEvent

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

Diaktifkan setiap kali proses debug masalah target terjadi peristiwa instrumentasi.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

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