chrome.debugger

Descrizione

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

Autorizzazioni

debugger

Per utilizzare 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 comandi Chrome DevTools Protocol (CDP) a un determinato target. L'analisi approfondita di CDP non rientra nell'ambito di questa documentazione. Per scoprire di più su CDP, consulta la documentazione ufficiale di CDP.

Destinazioni

I target rappresentano qualcosa che è in fase di debug, ad esempio una scheda, un iframe o un worker. Ogni target è identificato da un UUID e ha un tipo associato (ad esempio iframe, shared_worker e altri).

All'interno di un target possono essere presenti più contesti di esecuzione. Ad esempio, gli iframe dello stesso processo non hanno un target univoco, ma sono rappresentati come contesti diversi a cui è possibile accedere da un singolo target.

Domini con limitazioni

Per motivi di sicurezza, l'API chrome.debugger non fornisce l'accesso a tutti i domini di protocollo di DevTools di Chrome. I domini disponibili sono: Accessibilità, Audit, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio e WebAuthn.

Lavorare con le cornici

Non esiste una mappatura uno a uno dei frame ai target. All'interno di una singola scheda, più frame dello stesso processo possono condividere lo stesso target, ma utilizzare un contesto di esecuzione diverso. D'altra parte, è possibile creare un nuovo target per un iframe out-of-process.

Per eseguire il collegamento a tutti i frame, devi gestire ogni tipo di frame separatamente:

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

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

Allega ai target correlati

Dopo aver eseguito la connessione a un target, ti consigliamo di collegarti ad altri target correlati, inclusi frame secondari out-of-process o worker associati.

A partire da Chrome 125, l'API chrome.debugger supporta le sessioni piatte. In questo modo, puoi aggiungere altri target come figli alla sessione di debugger principale e inviare loro messaggi senza dover effettuare un'altra chiamata a chrome.debugger.attach. Al contrario, puoi aggiungere una proprietà sessionId quando chiami chrome.debugger.sendCommand per identificare il target secondario a cui vuoi inviare un comando.

Per collegarti automaticamente ai frame secondari out of process, aggiungi prima un ascoltatore 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, attiva l'aggancio 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 }]
});

L'attacco automatico si applica solo ai frame di cui è a conoscenza il target, ovvero ai frame che sono elementi secondari immediati di un frame associato. Ad esempio, con la gerarchia di frame A -> B -> C (dove tutti sono cross-origin), la chiamata a Target.setAutoAttach per il target associato ad A comporterà l'associazione della sessione anche a B. Tuttavia, non è ricorsiva, quindi Target.setAutoAttach deve essere chiamato anche per consentire a B di collegare la sessione a C.

Esempi

Per provare questa API, installa l'esempio di API di debugger dal repository chrome-extension-samples.

Tipi

Debuggee

Identificatore del debuggee. È necessario specificare tabId, extensionId o targetId

Proprietà

• extensionId

  stringa facoltativa

  L'ID dell'estensione che intendi eseguire il debug. L'attacco a una pagina di sfondo dell'estensione è possibile solo se viene utilizzato il parametro a riga di comando --silent-debugger-extension-api.

• tabId

  number facoltativo

  L'ID della scheda che intendi eseguire il debug.

• targetId

  stringa facoltativa

  L'ID opaco della destinazione di debug.

DebuggerSession

Chrome 125 e versioni successive

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

Proprietà

• extensionId

  stringa facoltativa

  L'ID dell'estensione che intendi eseguire il debug. L'attacco a una pagina di sfondo dell'estensione è possibile solo se viene utilizzato il parametro a riga di comando --silent-debugger-extension-api.

• sessionId

  stringa facoltativa

  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

  number facoltativo

  L'ID della scheda che intendi eseguire il debug.

• targetId

  stringa facoltativa

  L'ID opaco della destinazione di debug.

DetachReason

Chrome 44 e versioni successive

Motivo della terminazione della connessione.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informazioni sul target di debug

Proprietà

• collegato

  booleano

  True se il debugger è già collegato.

• extensionId

  stringa facoltativa

  L'ID estensione, definito se type = "background_page".

• faviconUrl

  stringa facoltativa

  URL della favicon di destinazione.

• id

  stringa

  ID target.

• tabId

  number facoltativo

  L'ID scheda, definito se type == "page".

• titolo

  stringa

  Titolo della pagina target.

• tipo

  TargetInfoType

  Tipo di target.

• url

  stringa

  URL di destinazione.

TargetInfoType

Chrome 44 e versioni successive

Tipo di target.

Enum

"page"

"background_page"

"worker"

"other"

Metodi

attach()

Promessa

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

Collega il debugger al target specificato.

Parametri

• target

  Individuo da eseguire il debug

  Destinazione di debug a cui vuoi eseguire l'attacco.

• requiredVersion

  stringa

  Versione del protocollo di debug richiesta ("0.1"). È possibile collegarsi al programma da eseguire il debug solo con una versione principale corrispondente e una versione secondaria maggiore o uguale. L'elenco delle versioni del protocollo è disponibile qui.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 96 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

detach()

Promessa

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

Scollega il debugger dal target specificato.

Parametri

• target

  Individuo sottoposto a debug

  Destinazione di debug da cui vuoi scollegare.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 96 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getTargets()

Promessa

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

Restituisce l'elenco dei target di debug disponibili.

Parametri

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (result: TargetInfo[]) => void

  • risultato

    TargetInfo[]

    Array di oggetti TargetInfo corrispondenti ai target di debug disponibili.

Resi

• Promise<TargetInfo[]>

  Chrome 96 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

sendCommand()

Promessa

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

Invia il comando specificato al target di debug.

Parametri

• target

  DebuggerSession

  Destinazione 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 i parametri di richiesta. Questo oggetto deve essere conforme allo schema dei parametri di debug remoto per un determinato metodo.

• callback

  function 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 dall'attributo "returns" della descrizione del comando nel protocollo di debug remoto.

Resi

• Promise<object | undefined>

  Chrome 96 e versioni successive

  Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

Eventi

onDetach

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

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

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

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

  • origine

    Individuo sottoposto a debug

  • motivo

    DetachReason

onEvent

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

Viene attivato ogni volta che il target di debug genera un evento di misurazione.

Parametri

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

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

  • origine

    DebuggerSession

  • method

    stringa

  • params

    Oggetto facoltativo