chrome.debugger

Descrizione

L'API chrome.debugger funge da trasporto alternativo per il protocollo di debug remoto di Chrome. Usa chrome.debugger per collegarti a una o più schede per analizzare l'interazione con la rete, eseguire il debug di JavaScript, modificare DOM e CSS e altro ancora. Utilizza la proprietà Debuggee tabId per scegliere come target le schede con sendCommand e indirizzare gli eventi in base a tabId dalle richiamate onEvent.

Autorizzazioni

debugger

Per usare questa API, devi dichiarare l'autorizzazione "debugger" nel file manifest dell'estensione.

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

Concetti e utilizzo

Una volta collegata, l'API chrome.debugger ti consente di inviare il protocollo Chrome DevTools (CDP) a una determinata destinazione. Una spiegazione approfondita del CDP non rientra nell'ambito per questa documentazione. Per saperne di più su CDP, consulta documentazione ufficiale CDP.

Destinazioni

Le destinazioni rappresentano un elemento di cui viene eseguito il debug, ad esempio una scheda, un iframe o un worker. Ogni target viene identificato da un UUID e ha un associato (ad esempio iframe, shared_worker e altri).

All'interno di un target, potrebbero esserci più contesti di esecuzione, ad esempio lo stesso gli iframe del processo non ricevono un target univoco, ma sono rappresentati come contesti diversi a cui è possibile accedere da una singola destinazione.

Domini con limitazioni

Per motivi di sicurezza, l'API chrome.debugger non fornisce accesso a tutti i Chrome DevTools Domini Protocolli. I domini disponibili sono: Accessibilità, Controlli, CacheStorage, console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulazione, Recupero, IO, Input, Ispezione, Log, Rete, Overlay, Pagina, Rendimento, Profiler, Runtime, archiviazione, destinazione, tracciamento, WebAudio e WebAuthn.

Lavora con i frame

Non esiste una mappatura 1:1 dei frame alle destinazioni. All'interno di una sola scheda, più frame di processo uguali possono condividere lo stesso target ma utilizzare un contesto di esecuzione. Un nuovo target può invece essere creato per un iframe out-of-process.

Per agganciarlo a tutte le cornici, devi gestire ogni tipo di cornice separatamente:

• Ascolta l'evento Runtime.executionContextCreated per identificarne di nuovi contesti di esecuzione associati agli stessi frame di processo.

• Segui i passaggi per eseguire l'associazione ai target correlati per: identificare i frame out-of-process.

Associa a target correlati

Dopo aver effettuato il collegamento a una destinazione, potrebbe essere utile stabilire un collegamento con altre destinazioni correlate inclusi i frame secondari out-of-process o i worker associati.

A partire da Chrome 125, l'API chrome.debugger supporta le sessioni piatte. Questo consente di aggiungere target aggiuntivi come elementi secondari alla sessione debugger principale invia loro un messaggio senza dover effettuare un'altra chiamata al numero chrome.debugger.attach. Invece, puoi aggiungere una proprietà sessionId quando chiami chrome.debugger.sendCommand a identificare il target figlio a cui inviare un comando.

Per collegarti automaticamente ai frame secondari out-of-process, aggiungi prima un listener per l'evento 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");
  }
});

Quindi, abilita il collegamento automatico inviando il comando Target.setAutoAttach con l'opzione flatten impostata su true:

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

Esempi

Per provare questa API, installa l'esempio dell'API debugger da chrome-extension-samples repository Git.

Tipi

Debuggee

Identificatore debuggee. È necessario specificare tabId, extensionId o targetId

Proprietà

• extensionId

  stringa facoltativo

  L'ID dell'estensione di cui intendi eseguire il debug. È possibile eseguire il collegamento a una pagina in background con un'estensione solo quando si utilizza l'opzione della riga di comando --silent-debugger-extension-api.

• tabId

  numero facoltativo

  L'ID della scheda di cui vuoi eseguire il debug.

• targetId

  stringa facoltativo

  L'ID opaco della destinazione di debug.

DebuggerSession

Chrome 125 e versioni successive .

Identificatore sessione debugger. È necessario specificare uno tra tabId, extensionId o targetId. Inoltre, è possibile fornire un sessionId facoltativo. Se sessionId viene specificato per gli argomenti inviati da onEvent, significa che l'evento proviene da una sessione di protocollo figlio all'interno della sessione di debuggee principale. Se sessionId viene specificato quando viene passato a sendCommand, sceglie come target una sessione di protocollo figlio all'interno della sessione di debuggee principale.

Proprietà

• extensionId

  stringa facoltativo

  L'ID dell'estensione di cui intendi eseguire il debug. È possibile eseguire il collegamento a una pagina in background con un'estensione solo quando si utilizza l'opzione della riga di comando --silent-debugger-extension-api.

• sessionId

  stringa facoltativo

  L'ID opaco della sessione del protocollo Chrome DevTools. Identifica una sessione secondaria all'interno della sessione principale identificata da tabId, extensionId o targetId.

• tabId

  numero facoltativo

  L'ID della scheda di cui vuoi eseguire il debug.

• targetId

  stringa facoltativo

  L'ID opaco della destinazione di debug.

DetachReason

Chrome 44 e versioni successive .

Motivo dell'interruzione della connessione.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informazioni sulla destinazione di debug

Proprietà

• collegato

  booleano

  True se il debugger è già collegato.

• extensionId

  stringa facoltativo

  L'ID dell'estensione, definito se il tipo = "background_page".

• faviconUrl

  stringa facoltativo

  URL della favicon target.

• id

  stringa

  ID target.

• tabId

  numero facoltativo

  L'ID scheda, definito se il tipo == "pagina".

• titolo

  stringa

  Titolo pagina di destinazione.

• tipo

  TargetInfoType

  Tipo di target.

• url

  stringa

  URL di destinazione.

TargetInfoType

Chrome 44 e versioni successive .

Tipo di target.

Enum

"pagina"

"background_page"

"worker"

"altro"

Metodi

attach()

Promesso .

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

Collega il debugger alla destinazione specificata.

Parametri

• target

  Debuggee

  Debug della destinazione a cui vuoi collegarti.

• requiredVersion

  stringa

  Versione del protocollo di debug obbligatoria ("0.1"). Uno può collegarsi al debuggee solo con una versione principale corrispondente e una versione secondaria superiore o uguale. L'elenco delle versioni del protocollo è disponibile qui.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promesso<void>

  Chrome 96 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

detach()

Promesso .

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

Stacca il debugger dalla destinazione specificata.

Parametri

• target

  Debuggee

  Target di debug da cui vuoi scollegarti.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promesso<void>

  Chrome 96 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

getTargets()

Promesso .

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

Restituisce l'elenco dei target di debug disponibili.

Parametri

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (result: TargetInfo[]) => void

  • risultato

    TargetInfo[]

    Matrice di oggetti TargetInfo corrispondente alle destinazioni di debug disponibili.

Resi

• Promise&lt;TargetInfo[]&gt;

  Chrome 96 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

sendCommand()

Promesso .

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

Invia il comando specificato alla destinazione di debug.

Parametri

• target

  DebuggerSession

  Target di debug a cui vuoi inviare il comando.

• method

  stringa

  Nome del metodo. Deve essere uno dei metodi definiti dal protocollo di debug remoto.

• commandParams

  oggetto facoltativo

  Oggetto JSON con parametri di richiesta. Questo oggetto deve essere conforme allo schema dei parametri di debug remoto per il metodo specificato.

• callback

  funzione facoltativa

  Il parametro callback ha il seguente aspetto:

  (result?: object) => void

  • risultato

    oggetto facoltativo

    oggetto JSON con la risposta. La struttura della risposta varia a seconda del nome del metodo ed è definita dal parametro "returns" della descrizione del comando nel protocollo di debug remoto.

Resi

• Promise&lt;object | non definito>

  Chrome 96 e versioni successive .

  Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.

Eventi

onDetach

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

Attivato quando il browser termina la sessione di debug per la scheda. Questo accade quando la scheda viene chiusa o Chrome DevTools viene richiamato per la scheda collegata.

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

  (source: Debuggee, reason: DetachReason) => void

  • origine

    Debuggee

  • motivo

    DetachReason

onEvent

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

Attivato ogni volta che il debug del target genera un evento di strumentazione.

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

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

  • origine

    DebuggerSession

  • method

    stringa

  • parametri

    oggetto facoltativo