Description
L'API chrome.debugger
sert de moyen de transport alternatif pour le protocole de débogage à distance de Chrome. Utilisez chrome.debugger
pour l'associer à un ou plusieurs onglets afin d'instrumenter les interactions réseau, de déboguer JavaScript, de modifier le DOM et le CSS, etc. Utilisez la propriété Debuggee
tabId
pour cibler les onglets avec sendCommand
et acheminer les événements par tabId
à partir des rappels onEvent
.
Autorisations
debugger
Pour utiliser cette API, vous devez déclarer l'autorisation "debugger"
dans le fichier manifeste de votre extension.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
Concepts et utilisation
Une fois associée, l'API chrome.debugger
vous permet d'envoyer des commandes CDP (Chrome DevTools Protocol) à une cible donnée. Cette documentation ne couvre pas le CDP en détail. Pour en savoir plus, consultez la documentation officielle du CDP.
Cibles
Les cibles représentent un élément en cours de débogage. Il peut s'agir d'un onglet, d'un iFrame ou d'un nœud de calcul. Chaque cible est identifiée par un UUID et est associée à un type (par exemple, iframe
, shared_worker
, etc.).
Une cible peut comporter plusieurs contextes d'exécution. Par exemple, les iFrames d'un même processus n'ont pas de cible unique, mais sont représentés par des contextes différents accessibles à partir d'une seule cible.
Domaines restreints
Pour des raisons de sécurité, l'API chrome.debugger
ne permet pas d'accéder à tous les domaines du protocole des outils pour les développeurs Chrome. , Database, Debugger, DOM, DOMDebugger, DOMSnapshot,dOMSnapshotCacheStorageWebAudioWebAuthn
Utiliser des cadres
Il n'y a pas de mappage entre une et une des images sur les cibles. Dans un même onglet, plusieurs images de processus identiques peuvent partager la même cible, mais utiliser un contexte d'exécution différent. D'autre part, une cible peut être créée pour un iFrame hors processus.
Pour joindre tous les cadres, vous devez gérer chaque type de cadre séparément:
Écoutez l'événement
Runtime.executionContextCreated
pour identifier de nouveaux contextes d'exécution associés aux mêmes frames de processus.Suivez la procédure permettant de l'associer à des cibles associées afin d'identifier les frames hors processus.
Associer à des cibles associées
Après vous être connecté à une cible, vous souhaiterez peut-être vous connecter à d'autres cibles associées, y compris aux cadres enfants ou aux nœuds de calcul associés hors processus.
À partir de Chrome 125, l'API chrome.debugger
accepte les sessions plates. Cela vous permet d'ajouter des cibles supplémentaires en tant qu'enfants à votre session de débogage principale et de leur envoyer un message sans avoir à appeler chrome.debugger.attach
à nouveau. À la place, vous pouvez ajouter une propriété sessionId
lorsque vous appelez chrome.debugger.sendCommand
pour identifier la cible enfant à laquelle vous souhaitez envoyer une commande.
Pour l'associer automatiquement à des frames enfants hors traitement, ajoutez d'abord un écouteur pour l'événement 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");
}
});
Ensuite, activez l'association automatique en envoyant la commande Target.setAutoAttach
avec l'option flatten
définie sur true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
Exemples
Pour essayer cette API, installez l'exemple d'API du débogueur à partir du dépôt chrome-extension-samples.
Types
Debuggee
Identifiant de l'élément à déboguer. Vous devez indiquer la valeur tabId, extensionId ou targetId
Propriétés
-
extensionId
string facultatif
Identifiant de l'extension que vous souhaitez déboguer. L'association à la page d'arrière-plan d'une extension n'est possible que lorsque le commutateur de ligne de commande
--silent-debugger-extension-api
est utilisé. -
tabId
numéro facultatif
ID de l'onglet que vous souhaitez déboguer.
-
targetId
string facultatif
Identifiant opaque de la cible de débogage.
DebuggerSession
Identifiant de session de débogueur. Vous devez spécifier la valeur tabId, extensionId ou targetId. Un ID de session facultatif peut également être fourni. Si sessionId est spécifié pour les arguments envoyés à partir de onEvent
, cela signifie que l'événement provient d'une session de protocole enfant de la session de débogage racine. Si sessionId est spécifié lorsqu'il est transmis à sendCommand
, il cible une session de protocole enfant dans la session de débogage racine.
Propriétés
-
extensionId
string facultatif
Identifiant de l'extension que vous souhaitez déboguer. L'association à la page d'arrière-plan d'une extension n'est possible que lorsque le commutateur de ligne de commande
--silent-debugger-extension-api
est utilisé. -
sessionId
string facultatif
ID opaque de la session du protocole des outils pour les développeurs Chrome. Identifie une session enfant au sein de la session racine identifiée par tabId, extensionId ou targetId.
-
tabId
numéro facultatif
ID de l'onglet que vous souhaitez déboguer.
-
targetId
string facultatif
Identifiant opaque de la cible de débogage.
DetachReason
Motif de l'interruption de la connexion.
Enum
"target_closed"
"canceled_by_user"
TargetInfo
Informations sur la cible de débogage
Propriétés
-
associé
boolean
"True" si le débogueur est déjà associé.
-
extensionId
string facultatif
ID de l'extension, défini si le type = "background_page".
-
faviconUrl
string facultatif
URL du favicon cible
-
id
chaîne
ID cible.
-
tabId
numéro facultatif
ID de l'onglet, défini si le type == 'page'.
-
title
chaîne
Titre de la page cible.
-
Type
Type de cible.
-
url
chaîne
URL cible.
TargetInfoType
Type de cible.
Enum
"page"
"background_page"
"worker"
Méthodes
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Associe le débogueur à la cible donnée.
Paramètres
-
cible
Cible de débogage à laquelle vous souhaitez l'associer.
-
requiredVersion
chaîne
Version de protocole de débogage requise ("0.1"). Une association à l'élément à déboguer ne peut être associée qu'à la version majeure correspondante et à la version mineure supérieure ou égale. Pour obtenir la liste des versions de protocole, cliquez ici.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Dissocie le débogueur de la cible donnée.
Paramètres
-
cible
Cible de débogage dont vous souhaitez vous dissocier.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Renvoie la liste des cibles de débogage disponibles.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: TargetInfo[]) => void
-
résultat
Tableau d'objets TargetInfo correspondant aux cibles de débogage disponibles.
-
Renvoie
-
Promise<TargetInfo[]>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Envoie la commande donnée à la cible de débogage.
Paramètres
-
cible
Cible de débogage à laquelle vous souhaitez envoyer la commande.
-
method
chaîne
Nom de la méthode. Elle doit correspondre à l'une des méthodes définies par le protocole de débogage distant.
-
commandParams
objet facultatif
Objet JSON avec des paramètres de requête. Cet objet doit être conforme au schéma des paramètres de débogage à distance pour la méthode donnée.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result?: object) => void
-
résultat
objet facultatif
Objet JSON avec la réponse. La structure de la réponse varie en fonction du nom de la méthode et est définie par l'attribut "returns" de la description de la commande dans le protocole de débogage à distance.
-
Renvoie
-
Promise<object | undefined>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
Déclenché lorsque le navigateur met fin à la session de débogage pour l'onglet. Cela se produit lorsque l'onglet est fermé ou que les outils pour les développeurs Chrome sont appelés pour l'onglet associé.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(source: Debuggee, reason: DetachReason) => void
-
source
-
reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Déclenché chaque fois que le débogage cible un problème d'instrumentation.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
chaîne
-
params
objet facultatif
-