chrome.debugger (original) (raw)

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:

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, quindiTarget.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à

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à

DetachReason

Chrome 44 e versioni successive

Motivo della terminazione della connessione.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Informazioni sul target di debug

Proprietà

TargetInfoType

Chrome 44 e versioni successive

Tipo di target.

Enum

"page"

"background_page"

"worker"

"other"

Metodi

attach()

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

Collega il debugger al target specificato.

Parametri

Resi

detach()

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

Scollega il debugger dal target specificato.

Parametri

Resi

getTargets()

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

Restituisce l'elenco dei target di debug disponibili.

Parametri

Resi

sendCommand()

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

Invia il comando specificato al target di debug.

Parametri

Resi

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

onEvent

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

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

Parametri