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 connecter à un ou plusieurs onglets afin d'instrumenter l'interaction réseau, de déboguer JavaScript, de modifier le DOM et le CSS, et plus encore. Utilisez la Debuggee propriété tabId pour cibler les onglets avec sendCommand et acheminer les événements par tabId à partir des rapp5/} 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",
  ],
  ...
}

Restrictions liées aux règles d'entreprise

Sur les appareils d'entreprise, certaines règles peuvent empêcher les extensions de joindre le débogueur à l'aide d'un modèle tout ou rien au moment de la connexion (chrome.debugger.attach()) :

  • Restrictions d'hôte : si la règle d'entreprise ExtensionSettings configure des hôtes bloqués (runtime_blocked_hosts) pour une extension, chrome.debugger.attach() est bloqué sur toutes les cibles avec l'erreur "Host access is restricted by policy." (même si des origines individuelles se trouvent dans runtime_allowed_hosts).
  • Règles concernant les captures d'écran et la protection contre la perte de données : si la règle d'entreprise DisableScreenshots désactive la capture d'écran ou si des règles de protection contre la perte de données s'appliquent à la cible, chrome.debugger.attach() échoue avec l'erreur "Screenshot capture is restricted by policy.".

Concepts et utilisation

Une fois connecté, l'API chrome.debugger vous permet d'envoyer des commandes du protocole Chrome DevTools (CDP) à une cible donnée. L'explication détaillée du CDP ne fait pas partie de cette documentation. Pour en savoir plus, consultez la documentation officielle du CDP.

Cibles

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

Dans une cible, il peut y avoir plusieurs contextes d'exécution. Par exemple, les iframes du même processus n'obtiennent pas de cible unique, mais sont représentés comme des contextes différents accessibles à partir d'une seule cible.

Domaines restreints

Pour des raisons de sécurité, l'API chrome.debugger ne donne pas accès à tous les domaines du protocole Chrome DevTools. Les domaines disponibles sont les suivants : Accessibility, 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 frames

Il n'existe pas de mappage un-à-un entre les frames et les cibles. Dans un même onglet, plusieurs frames du même processus 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 vous connecter à toutes les frames, vous devez gérer chaque type de frame séparément :

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

  • Suivez les étapes pour vous connecter aux cibles associées afin d' identifier les frames hors processus.

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

À partir de Chrome 125, l'API chrome.debugger est compatible avec les sessions plates. Cela vous permet d'ajouter d'autres cibles en tant qu'enfants à votre session de débogage principale et de leur envoyer des messages sans avoir à effectuer un autre appel à chrome.debugger.attach. 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 vous connecter automatiquement aux 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");
  }
});

Ensuite, activez la connexion 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 }]
});

La connexion automatique ne se connecte qu'aux frames dont la cible est consciente, ce qui se limite aux frames qui sont des enfants immédiats d'une frame qui lui est associée. Par exemple, avec la hiérarchie de frames A -> B -> C (où toutes sont inter-origines), l'appel de Target.setAutoAttach pour la cible associée à A entraîne également la connexion de la session à B. Toutefois, cela n'est pas récursif. Vous devez donc également appeler Target.setAutoAttach pour B afin de connecter la session à C.

Exemples

Pour essayer cette API, installez l'exemple d'API de débogueur à 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 facultative

    ID de l'extension que vous souhaitez déboguer. La connexion à 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

    nombre facultatif

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

  • targetId

    chaîne facultative

    ID opaque de la cible de débogage.

DebuggerSession

Chrome 125+

Identifiant de session du débogueur. Vous devez spécifier 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 au sein de la session de l'élément débogué racine. Si sessionId est spécifié lorsqu'il est transmis à sendCommand, il cible une session de protocole enfant au sein de la session de l'élément débogué racine.

Propriétés

  • extensionId

    chaîne facultative

    ID de l'extension que vous souhaitez déboguer. La connexion à 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 facultative

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

  • tabId

    nombre facultatif

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

  • targetId

    chaîne facultative

    ID opaque de la cible de débogage.

DetachReason

Chrome 44+

Raison 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

    La valeur est "true" si le débogueur est déjà connecté.

  • extensionId

    chaîne facultative

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

  • faviconUrl

    chaîne facultative

    URL du favicon cible.

  • id

    chaîne

    ID de la cible.

  • tabId

    nombre facultatif

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

  • titre

    chaîne

    Titre de la page cible.

  • Type de cible.

  • url

    chaîne

    URL cible.

TargetInfoType

Chrome 44+

Type de cible.

Énumération

"page"

"background_page"

"worker"

"other"

Méthodes

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

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

Paramètres

  • cible

    Debuggee

    Cible de débogage à laquelle vous souhaitez vous connecter.

  • requiredVersion

    chaîne

    Version requise du protocole de débogage ("0.1"). Vous ne pouvez vous connecter à l'élément débogué qu'avec une version majeure correspondante et une version mineure supérieure ou égale. La liste des versions du protocole est disponible ici.

Renvoie

  • Promise<void>

    Chrome 96+

    Se résout une fois que l'opération de connexion a réussi ou échoué. La promesse se résout sans valeur. Si la connexion échoue, la promesse est rejetée.

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

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

Paramètres

  • cible

    Debuggee

    Cible de débogage de laquelle vous souhaitez vous déconnecter.

Renvoie

  • Promise<void>

    Chrome 96+

    Se résout une fois que l'opération de déconnexion a réussi ou échoué. La promesse se résout sans valeur. Si la déconnexion échoue, la promesse est rejetée.

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

Renvoie la liste des cibles de débogage disponibles.

Renvoie

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

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 être 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 à distance pour la méthode donnée.

Renvoie

  • Promise<object | undefined>

    Chrome 96+

    Corps de la réponse. Si une erreur se produit lors de la publication du message, la promesse est rejetée.

É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 associé.

Paramètres

onEvent

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

Déclenché chaque fois que la cible de débogage émet 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