chrome.debugger

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 le tabId Debuggee 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.

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

Chrome 125 et versions ultérieures

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

Chrome 44 ou version ultérieure

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 de cible.

  • url

    chaîne

    URL cible.

TargetInfoType

Chrome 44 ou version ultérieure

Type de cible.

Enum

"page"

"background_page"

"worker"

Méthodes

attach()

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

Associe le débogueur à la cible donnée.

Paramètres

  • 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érieures

    Les 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()

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

Dissocie le débogueur de la cible donnée.

Paramètres

  • 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érieures

    Les 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()

Promesse 
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

      TargetInfo[]

      Tableau d'objets TargetInfo correspondant aux cibles de débogage disponibles.

Renvoie

  • Promise<TargetInfo[]>

    Chrome 96 et versions ultérieures

    Les 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()

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

Envoie la commande donnée à la cible de débogage.

Paramètres

  • 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érieures

    Les 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

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