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 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 Debuggee pour cibler les onglets avec sendCommand et acheminer les événements par tabId à partir de rappels onEvent.

Autorisations

debugger

Vous devez déclarer l'autorisation "debugger" dans le fichier manifeste de votre extension pour utiliser cette API.

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

Concepts et utilisation

Une fois associée, l'API chrome.debugger vous permet d'envoyer le protocole d'outils pour les développeurs Chrome (CDP) à une cible donnée. Expliquer en détail la CDP n'entre pas dans le champ d'application pour cette documentation. Pour en savoir plus sur la CDP, consultez documentation officielle de la CDP.

Cibles

Les cibles représentent un élément en cours de débogage : il peut s'agir d'un onglet, comme un iFrame ou un worker. Chaque cible est identifiée par un UUID et dispose d'un (iframe, shared_worker, etc.).

Une cible peut comporter plusieurs contextes d'exécution (par exemple, le même Les iFrames du processus n'ont pas de cible unique, mais sont représentés différents contextes accessibles à partir d'une même cible.

Domaines restreints

Pour des raisons de sécurité, l'API chrome.debugger ne permet pas d'accéder à tous les outils pour les développeurs Chrome Domaines de protocole. Les domaines disponibles sont les suivants: Accessibilité, Audits, CacheStorage, Console CSS, base de données, Debugger, DOM, DOMDebugger, DOMSnapshot, Émulation, Récupération, E/S, Entrée. Inspecteur, journal, réseau, superposition, Page, Performance, Profiler, Exécution, Stockage, Cible, Traçage. WebAudio et WebAuthn.

Utiliser des cadres

Il n'existe pas de mappage "un à un" des trames sur les cibles. Dans un même onglet, plusieurs trames de processus peuvent partager la même cible, mais utiliser un autre contexte d'exécution. À l'inverse, une nouvelle cible peut être créé pour un iFrame hors processus.

Pour attacher tous les cadres, vous devez gérer chaque type de cadre séparément:

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

  • Suivez la procédure d'association à des cibles associées pour identifier les trames hors processus.

Une fois connecté à une cible, vous pouvez vous connecter à d'autres cibles associées y compris les frames enfants hors traitement ou les nœuds de calcul associés.

À partir de Chrome 125, l'API chrome.debugger est compatible avec les sessions plates. Ce vous permet d'ajouter des cibles supplémentaires en tant qu'enfants à votre session de débogage principale et envoyez-leur un message sans avoir besoin d'un autre appel vers 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 l'associer automatiquement à des frames 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");
  }
});

Activez ensuite 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 de débogage à partir de chrome-extension-samples. un dépôt de clés.

Types

Debuggee

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

Propriétés

  • extensionId

    chaîne facultatif

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

  • tabId

    numéro facultatif

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

  • targetId

    chaîne facultatif

    ID opaque de la cible de débogage.

DebuggerSession

Chrome 125 ou version ultérieure

Identifiant de session du débogueur. Vous devez indiquer tabId, extensionId ou targetId. Vous pouvez également fournir un ID de session facultatif. Si sessionId est spécifié pour les arguments envoyés depuis onEvent, cela signifie que l'événement provient d'une session de protocole enfant dans la session racine à déboguer. Si sessionId est spécifié lors de sa transmission à sendCommand, il cible une session de protocole enfant dans la session racine à déboguer.

Propriétés

  • extensionId

    chaîne facultatif

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

  • sessionId

    chaîne facultatif

    ID opaque de la session du protocole des outils pour les développeurs Chrome. Identifie une session enfant dans la session racine identifiée par tabId, extensionId ou targetId.

  • tabId

    numéro facultatif

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

  • targetId

    chaîne facultatif

    ID opaque de la cible de débogage.

DetachReason

Chrome (version 44 ou ultérieure)

Motif de l'interruption 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 le type est "background_page".

  • faviconUrl

    chaîne facultatif

    URL du favicon cible.

  • id

    chaîne

    ID cible.

  • tabId

    numéro 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 (version 44 ou ultérieure)

Type de cible.

Énumération

"page"

"background_page"

"worker"

"autre"

Méthodes

attach()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

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

Paramètres

  • Cible de débogage à laquelle vous souhaitez l'associer.

  • requiredVersion

    chaîne

    Version du protocole de débogage requise ("0.1"). Vous ne pouvez joindre l'élément à déboguer qu'à la version majeure correspondante et à la version mineure supérieure ou égale. Pour obtenir la liste des versions du protocole, cliquez ici.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

detach()

<ph type="x-smartling-placeholder"></ph> 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 la dissocier.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getTargets()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.debugger.getTargets(
  callback?: function,
)

Affiche la liste des cibles de débogage disponibles.

Paramètres

  • rappel

    function 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&lt;TargetInfo[]&gt;

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

sendCommand()

<ph type="x-smartling-placeholder"></ph> 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 des paramètres de débogage distant pour la méthode donnée.

  • rappel

    function facultatif

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

    (result?: object) => void

    • résultat

      objet facultatif

      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 les valeurs de la description de la commande dans le protocole de débogage à distance.

Renvoie

  • Promise&lt;object | indéfini>

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 de 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 joint.

Paramètres

onEvent

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

Déclenché chaque fois que le débogage de la cible rencontre un problème d'événement d'instrumentation.

Paramètres

  • rappel

    fonction

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

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