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 instrumentare l'interazione di rete, eseguire il debug di JavaScript, modificare il 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 dai callback onEvent.

Autorizzazioni

debugger

Per utilizzare questa API, devi dichiarare l'autorizzazione "debugger" nel 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 una determinata destinazione. La spiegazione dettagliata della CDP non rientra nell'ambito di questa documentazione. Per saperne di più, consulta la documentazione ufficiale della CDP.

Destinazioni

I target rappresentano qualcosa che viene sottoposto a 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 esistere più contesti di esecuzione. Ad esempio, gli iframe dello stesso processo non ottengono un target univoco, ma sono rappresentati come contesti diversi a cui è possibile accedere da un unico target.

Domini con restrizioni

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

Utilizzare i frame

Non esiste una mappatura uno a uno dei frame alle destinazioni. 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 allegare a tutti i frame, devi gestire separatamente ogni tipo di frame:

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

  • Segui i passaggi per collegare i target correlati per identificare i frame out-of-process.

Dopo aver eseguito la connessione a una destinazione, potresti voler connetterti ad 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. In questo modo puoi aggiungere altri target come figli alla sessione di debug principale e inviare loro messaggi senza dover effettuare un'altra chiamata a chrome.debugger.attach. In alternativa, puoi aggiungere una proprietà sessionId quando chiami chrome.debugger.sendCommand per identificare il target secondario a cui vuoi inviare un comando.

Per eseguire automaticamente l'attach ai frame secondari out-of-process, aggiungi innanzitutto 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");
  }
});

Poi, attiva l'allegato 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'allegato automatico viene applicato solo ai frame di cui è a conoscenza la destinazione, ovvero solo ai frame che sono elementi secondari immediati di un frame associato. Ad esempio, con la gerarchia dei frame A -> B -> C (dove tutti sono cross-origin), la chiamata Target.setAutoAttach per la destinazione associata ad A comporterebbe l'allegamento della sessione anche a B. Tuttavia, questa operazione non è ricorsiva, quindi deve essere chiamato anche Target.setAutoAttach per collegare la sessione a C.

Esempi

Per provare questa API, installa l'esempio di API di debug 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'associazione a una pagina di sfondo dell'estensione è possibile solo quando viene utilizzato l'opzione 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+

Identificatore della sessione del debugger. È necessario specificare 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 del protocollo secondario all'interno della sessione di debuggee principale. Se sessionId viene specificato quando viene passato a sendCommand, ha come target una sessione del protocollo secondario all'interno della sessione di debuggee radice.

Proprietà

  • extensionId

    stringa facoltativa

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

  • sessionId

    stringa facoltativa

    L'ID opaco della sessione Chrome DevTools Protocol. 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+

Motivo della chiusura 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 di target.

  • url

    stringa

    URL di destinazione.

TargetInfoType

Chrome 44+

Tipo di target.

Enum

"page"

"background_page"

"worker"

"other"

Metodi

attach()

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

Collega il debugger al target specificato.

Parametri

  • target

    Debuggee

    Target di debug a cui vuoi collegarti.

  • requiredVersion

    stringa

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

Resi

  • Promise<void>

    Chrome 96+

detach()

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

Scollega il debugger dalla destinazione specificata.

Parametri

  • target

    Debuggee

    Target di debug da cui vuoi scollegarti.

Resi

  • Promise<void>

    Chrome 96+

getTargets()

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

Restituisce l'elenco delle destinazioni di debug disponibili.

Resi

sendCommand()

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

Invia il comando specificato al target di debug.

Parametri

  • 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 della richiesta. Questo oggetto deve essere conforme allo schema dei parametri di debug remoto per il metodo specificato.

Resi

  • Promise<object | undefined>

    Chrome 96+

Eventi

onDetach

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

Attivato quando il browser termina la sessione di debug per la scheda. Ciò si verifica quando la scheda viene chiusa o quando vengono richiamati gli strumenti di sviluppo di Chrome per la scheda collegata.

Parametri

onEvent

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

Attivato ogni volta che viene generato l'evento di strumentazione dei problemi relativi alla destinazione di debug.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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