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 strumentare 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 indirizzare gli eventi tramite tabId dai callback onEvent.

Autorizzazioni

debugger

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

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

Limitazioni previste dai criteri aziendali

Sui dispositivi aziendali, alcuni criteri possono impedire alle estensioni di collegare il debugger utilizzando un modello tutto o niente al momento del collegamento (chrome.debugger.attach()):

  • Limitazioni degli host: se il criterio aziendale ExtensionSettings configura gli host bloccati (runtime_blocked_hosts) per un'estensione, chrome.debugger.attach() viene bloccato su tutti i target con l'errore "Host access is restricted by policy." (anche se le singole origini sono in runtime_allowed_hosts).
  • Criteri per screenshot e DLP: se il criterio aziendale DisableScreenshots disabilita l'acquisizione di screenshot o se le regole di Prevenzione della perdita di dati (DLP) si applicano al target, chrome.debugger.attach() non riesce e viene visualizzato l'errore "Screenshot capture is restricted by policy.".

Concetti e utilizzo

Una volta collegata, l'API chrome.debugger ti consente di inviare comandi Chrome DevTools Protocol (CDP) a un determinato target. La spiegazione approfondita del CDP non rientra nell'ambito di questa documentazione . Per saperne di più, consulta la documentazione ufficiale del CDP.

Target

I target rappresentano un elemento di cui viene eseguito il 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 altro ancora).

All'interno di un target possono essere presenti 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 singolo target.

Domini limitati

Per motivi di sicurezza, l'API chrome.debugger non fornisce l'accesso a tutti i domini di Chrome DevTools Protocol. I domini disponibili sono: Accessibility, Audits, 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.

Utilizzare i frame

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 collegarti a tutti i frame, devi gestire ogni tipo di frame separatamente:

  • Ascolta l'evento Runtime.executionContextCreated per identificare i nuovi contesti di esecuzione associati ai frame dello stesso processo.

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

Dopo aver eseguito la connessione a un target, potresti voler connetterti ad altri target correlati, inclusi i frame secondari out-of-process o i worker associati.

A partire da Chrome 125, l'API chrome.debugger supporta le sessioni flat. In questo modo puoi aggiungere altri target come figli alla sessione di debug principale e inviare loro messaggi senza dover chiamare di nuovo chrome.debugger.attach. In alternativa, puoi aggiungere una proprietà sessionId quando chiami chrome.debugger.sendCommand per identificare il target figlio a cui vuoi inviare un comando.

Per collegarti automaticamente 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");
  }
});

Quindi, attiva il collegamento automatico inviando il Target.setAutoAttach comando 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 }]
});

Il collegamento automatico si collega solo ai frame di cui il target è a conoscenza, ovvero solo ai frame che sono figli immediati di un frame associato. Ad esempio, con la gerarchia di frame A -> B -> C (dove tutti sono multiorigine), la chiamata di Target.setAutoAttach per il target associato ad A comporterebbe anche il collegamento della sessione a B. Tuttavia, questa operazione non è ricorsiva, quindi è necessario chiamare Target.setAutoAttach anche per B per collegare la sessione a C.

Esempi

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

Tipi

Debuggee

Identificatore debuggee. È necessario specificare tabId, extensionId o targetId

Proprietà

  • extensionId

    stringa facoltativa

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

  • tabId

    numero facoltativo

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

  • targetId

    stringa facoltativa

    L'ID opaco del target di debug.

DebuggerSession

Chrome 125+

Identificatore della sessione di debug. È necessario specificare 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 debuggee root. Se sessionId viene specificato quando viene passato a sendCommand, il target è una sessione di protocollo figlio all'interno della sessione debuggee root.

Proprietà

  • extensionId

    stringa facoltativa

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

  • sessionId

    stringa facoltativa

    L'ID opaco della sessione di Chrome DevTools Protocol. Identifica una sessione figlio all'interno della sessione root identificata da tabId, extensionId o targetId.

  • tabId

    numero facoltativo

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

  • targetId

    stringa facoltativa

    L'ID opaco del target di debug.

DetachReason

Chrome 44+

Motivo della terminazione della connessione.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informazioni sul target di debug

Proprietà

  • attached

    booleano

    True se il debugger è già collegato.

  • extensionId

    stringa facoltativa

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

  • faviconUrl

    stringa facoltativa

    URL favicon del target.

  • id

    stringa

    ID target.

  • tabId

    numero facoltativo

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

  • title

    stringa

    Titolo della pagina target.

  • Tipo di target.

  • url

    stringa

    URL target.

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 la versione principale corrispondente e la versione secondaria maggiore o uguale. L'elenco delle versioni del protocollo è disponibile qui.

Valori restituiti

  • Promise<void>

    Chrome 96+

    Si risolve quando l'operazione di collegamento ha esito positivo o negativo. La promessa si risolve senza alcun valore. Se il collegamento non riesce, la promessa verrà rifiutata.

detach()

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

Scollega il debugger dal target specificato.

Parametri

  • target

    Debuggee

    Target di debug da cui vuoi scollegarti.

Valori restituiti

  • Promise<void>

    Chrome 96+

    Si risolve quando l'operazione di scollegamento ha esito positivo o negativo. La promessa si risolve senza alcun valore. Se lo scollegamento non riesce, la promessa verrà rifiutata.

getTargets()

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

Restituisce l'elenco dei target di debug disponibili.

Valori restituiti

sendCommand()

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

Invia il comando specificato al target di debug.

Parametri

  • Target di debug a cui vuoi inviare il comando.

  • method

    stringa

    Nome 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.

Valori restituiti

  • Promise<object | undefined>

    Chrome 96+

    Corpo della risposta. Se si verifica un errore durante la pubblicazione del messaggio, la promessa verrà rifiutata.

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 quando Chrome DevTools viene richiamato per la scheda collegata.

Parametri

onEvent

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

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

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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