chrome.debugger

Deskripsi

chrome.debugger API berfungsi sebagai transportasi alternatif untuk protokol pen-debugan jarak jauh Chrome. Gunakan chrome.debugger untuk melampirkan ke satu atau beberapa tab untuk mengukur interaksi jaringan, men-debug JavaScript, memutasikan DOM dan CSS, dan banyak lagi. Gunakan properti Debuggee tabId untuk menargetkan tab dengan sendCommand dan mengarahkan peristiwa menurut tabId dari callback onEvent.

Izin

debugger

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

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

Konsep dan penggunaan

Setelah dilampirkan, chrome.debugger API memungkinkan Anda mengirim perintah Chrome DevTools Protocol (CDP) ke target tertentu. Penjelasan mendalam tentang CDP berada di luar cakupan dokumentasi ini. Untuk mempelajari CDP lebih lanjut, lihat dokumentasi resmi CDP.

Target

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

Dalam target, mungkin ada beberapa konteks eksekusi—misalnya, iframe proses yang sama tidak mendapatkan target unik, tetapi ditampilkan sebagai konteks berbeda yang dapat diakses dari satu target.

Domain yang dibatasi

Untuk alasan keamanan, chrome.debugger API tidak memberikan akses ke semua Domain Protokol Chrome DevTools. Domain yang tersedia adalah: Aksesibilitas, Audit, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulasi, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio, dan WebAuthn.

Bekerja dengan frame

Tidak ada pemetaan frame ke target satu per satu. Dalam satu tab, beberapa frame proses yang sama dapat berbagi target yang sama, tetapi menggunakan konteks eksekusi yang berbeda. Di sisi lain, target baru dapat dibuat untuk iframe di luar proses.

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

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

  • Ikuti langkah-langkah untuk melampirkan ke target terkait guna mengidentifikasi frame di luar proses.

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

Mulai Chrome 125, chrome.debugger API mendukung sesi datar. Hal ini memungkinkan Anda menambahkan target tambahan sebagai turunan ke sesi debugger utama dan mengirim pesan kepada mereka tanpa memerlukan panggilan lain ke chrome.debugger.attach. Sebagai gantinya, Anda dapat menambahkan properti sessionId saat memanggil chrome.debugger.sendCommand untuk mengidentifikasi target turunan yang ingin Anda kirimi perintah.

Untuk melampirkan secara otomatis ke frame turunan di luar proses, tambahkan terlebih dahulu 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 lampiran otomatis dengan mengirim perintah Target.setAutoAttach dengan opsi flatten yang ditetapkan ke true:

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

Penyematan otomatis hanya menyematkan ke frame yang diketahui target, yang terbatas pada frame yang merupakan turunan langsung dari frame yang terkait dengannya. Misalnya, dengan hierarki frame A -> B -> C (dengan semuanya lintas origin), memanggil Target.setAutoAttach untuk target yang terkait dengan A akan menyebabkan sesi juga dilampirkan ke B. Namun, hal ini tidak bersifat rekursif, jadi Target.setAutoAttach juga perlu dipanggil agar B dapat melampirkan sesi ke C.

Contoh

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

Jenis

Debuggee

ID yang di-debug. tabId, extensionId, atau targetId harus ditentukan

Properti

  • extensionId

    string opsional

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

  • tabId

    nomor opsional

    ID tab yang ingin Anda debug.

  • targetId

    string opsional

    ID buram target debug.

DebuggerSession

Chrome 125+

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, berarti peristiwa berasal dari sesi protokol turunan dalam sesi debuggee root. Jika sessionId ditentukan saat diteruskan ke sendCommand, ID tersebut akan menargetkan sesi protokol turunan dalam sesi debuggee root.

Properti

  • extensionId

    string opsional

    ID ekstensi yang ingin Anda debug. Proses melampirkan 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

    nomor opsional

    ID tab yang ingin Anda debug.

  • targetId

    string opsional

    ID buram target debug.

DetachReason

Chrome 44+

Alasan penghentian koneksi.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informasi target debug

Properti

  • terpasang

    boolean

    Benar (True) jika debugger sudah terpasang.

  • extensionId

    string opsional

    ID ekstensi, ditentukan jika type = 'background_page'.

  • faviconUrl

    string opsional

    URL favicon target.

  • id

    string

    ID target.

  • tabId

    nomor opsional

    ID tab, ditentukan jika type == 'page'.

  • judul

    string

    Judul halaman target.

  • Jenis target.

  • url

    string

    URL target.

TargetInfoType

Chrome 44+

Jenis target.

Enum

"halaman"

"background_page"

"worker"

"lainnya"

Metode

attach()

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

Melampirkan debugger ke target yang diberikan.

Parameter

  • target

    Debuggee

    Target pen-debugan yang ingin Anda lampirkan.

  • requiredVersion

    string

    Versi protokol debug yang diperlukan ("0.1"). Debugger hanya dapat dilampirkan ke target debug dengan versi utama yang cocok dan versi minor yang lebih besar atau sama. Daftar versi protokol dapat diperoleh di sini.

Hasil

  • Promise<void>

    Chrome 96+

detach()

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

Melepaskan debugger dari target yang diberikan.

Parameter

  • target

    Debuggee

    Target proses debug yang ingin Anda lepaskan.

Hasil

  • Promise<void>

    Chrome 96+

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

Menampilkan daftar target debug yang tersedia.

Hasil

sendCommand()

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

Mengirim perintah tertentu ke target proses debug.

Parameter

  • Target pen-debugan yang ingin Anda kirimi perintah.

  • method

    string

    Nama metode. Harus berupa salah satu metode yang ditentukan oleh protokol pen-debug-an jarak jauh.

  • commandParams

    objek opsional

    Objek JSON dengan parameter permintaan. Objek ini harus sesuai dengan skema parameter debug jarak jauh untuk metode tertentu.

Hasil

  • Promise<object | undefined>

    Chrome 96+

Acara

onDetach

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

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

Parameter

onEvent

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

Diaktifkan setiap kali men-debug peristiwa instrumentasi masalah target.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

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