chrome.debugger

Description

L'API chrome.debugger sert de transport alternatif pour le protocole de débogage à distance de Chrome. Utilisez chrome.debugger pour vous associer à un ou plusieurs onglets afin d'instrumenter l'interaction réseau, de déboguer JavaScript, de modifier le DOM et le CSS, etc. Utilisez la propriété tabId de la 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 connectée, l'API chrome.debugger vous permet d'envoyer des commandes Chrome DevTools Protocol (CDP) à une cible donnée. Il n'entre pas dans le champ d'application de cette documentation d'expliquer en détail le CDP. Pour en savoir plus, consultez la documentation officielle sur le CDP.

Cibles

Les cibles représentent un élément en cours de débogage, comme un onglet, une iframe ou un worker. Chaque cible est identifiée par un UUID et possède un type associé (iframe, shared_worker, etc.).

Dans une cible, il peut y avoir plusieurs contextes d'exécution. Par exemple, les iFrames du même processus ne reçoivent pas de cible unique, mais sont représentées par des contextes différents auxquels on peut accéder à partir d'une seule cible.

Domaines restreints

Pour des raisons de sécurité, l'API chrome.debugger n'offre pas d'accès à tous les domaines de protocole des outils pour les développeurs Chrome. Les domaines disponibles sont les suivants: Accessibilité, 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 et WebAuthn.

Utiliser des cadres

Il n'existe pas de mappage individuel des cadres aux cibles. Dans un seul onglet, plusieurs cadres de processus identiques peuvent partager la même cible, mais utiliser un contexte d'exécution différent. En revanche, une nouvelle cible peut être créée pour un iFrame hors processus.

Pour associer des éléments à tous les cadres, vous devez gérer chaque type de cadre séparément:

  • Écoutez l'événement Runtime.executionContextCreated pour identifier les nouveaux contextes d'exécution associés aux mêmes cadres de processus.

  • Suivez la procédure pour vous associer à des cibles associées afin d'identifier les cadres hors processus.

Après vous être connecté à une cible, vous pouvez vous connecter à d'autres cibles associées, y compris des cadres enfants hors processus ou des workers associés.

À partir de Chrome 125, l'API chrome.debugger est compatible avec 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 des messages sans avoir à appeler chrome.debugger.attach. À 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 associer automatiquement des cadres enfants hors processus, 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 }]
});

L'attachement automatique ne s'attache qu'aux cadres dont la cible a connaissance, ce qui est limité aux cadres qui sont des enfants immédiats d'un cadre qui lui est associé. Par exemple, avec la hiérarchie de cadres A -> B -> C (où tous sont multi-origines), l'appel de Target.setAutoAttach pour la cible associée à A entraînerait l'association de la session à B. Cependant, ce n'est pas récursif. Target.setAutoAttach doit donc également être appelé pour que B associe la session à C.

Exemples

Pour essayer cette API, installez l'exemple d'API de débogage à partir du dépôt chrome-extension-samples.

Types

Debuggee

Identifiant de l'élément débogué. Vous devez spécifier tabId, extensionId ou targetId.

Propriétés

  • extensionId

    chaîne facultatif

    ID de l'extension que vous souhaitez déboguer. L'association à une page d'arrière-plan d'extension n'est possible que lorsque l'option de ligne de commande --silent-debugger-extension-api est utilisée.

  • tabId

    number facultatif

    ID de l'onglet que vous souhaitez déboguer.

  • targetId

    chaîne facultatif

    ID opaque de la cible de débogage.

DebuggerSession

Chrome 125 et versions ultérieures

Identifiant de session du débogueur. Vous devez spécifier l'une des valeurs tabId, extensionId ou targetId. Vous pouvez également fournir un sessionId facultatif. 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 dans 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

    chaîne facultatif

    ID de l'extension que vous souhaitez déboguer. L'association à une page d'arrière-plan d'extension n'est possible que lorsque l'option de ligne de commande --silent-debugger-extension-api est utilisée.

  • sessionId

    chaîne facultatif

    ID opaque de la session du protocole Chrome DevTools. Identifie une session enfant dans la session racine identifiée par tabId, extensionId ou targetId.

  • tabId

    number facultatif

    ID de l'onglet que vous souhaitez déboguer.

  • targetId

    chaîne facultatif

    ID opaque de la cible de débogage.

DetachReason

Chrome 44 ou version ultérieure

Motif de la terminaison de la connexion.

Énumération

"target_closed"

"canceled_by_user"

TargetInfo

Informations sur la cible de débogage

Propriétés

  • associé

    booléen

    "True" si le débogueur est déjà associé.

  • extensionId

    chaîne facultatif

    ID de l'extension, défini si type = "background_page".

  • faviconUrl

    chaîne facultatif

    URL du favicon cible.

  • id

    chaîne

    ID de la cible.

  • tabId

    number facultatif

    ID de l'onglet, défini si type == "page".

  • titre

    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.

Énumération

"page"

"background_page"

"worker"

"other"

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 vous associer.

  • requiredVersion

    chaîne

    Version du protocole de débogage requise ("0.1"). Vous ne pouvez vous associer au débogueur qu'avec une version majeure correspondante et une version mineure supérieure ou égale. Vous trouverez la liste des versions du protocole sur cette page.

  • callback

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 96 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

detach()

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

Détache le débogueur de la cible donnée.

Paramètres

  • Cible de débogage à partir de laquelle vous souhaitez vous dissocier.

  • callback

    fonction facultatif

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 96 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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

  • callback

    fonction facultatif

    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 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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. Doit correspondre à l'une des méthodes définies par le protocole de débogage à distance.

  • commandParams

    objet facultatif

    Objet JSON avec des paramètres de requête. Cet objet doit être conforme au schéma de paramètres de débogage à distance pour une méthode donnée.

  • callback

    fonction facultatif

    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 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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 de l'onglet. Cela se produit lorsque l'onglet est fermé ou que les outils de développement Chrome sont appelés pour l'onglet associé.

Paramètres

onEvent

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

Déclenché chaque fois que la cible de débogage génère un événement d'instrumentation.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

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