browser.debugger

Descripción

La API de chrome.debugger funciona como un transporte alternativo para el protocolo de depuración remota de Chrome. Usa chrome.debugger para adjuntar una o más pestañas para instrumentar la interacción de red, depurar JavaScript, mutar el DOM y CSS, y mucho más. Usa la propiedad Debuggee tabId para segmentar pestañas con sendCommand y enrutar eventos por tabId desde devoluciones de llamada de onEvent.

Permisos

debugger

Debes declarar el permiso "debugger" en el manifiesto de tu extensión para usar esta API.

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

Restricciones de políticas empresariales

En los dispositivos empresariales, algunas políticas pueden restringir que las extensiones adjunten el depurador con un modelo de todo o nada en el momento de la vinculación (browser.debugger.attach()):

  • Restricciones de host: Si la política empresarial ExtensionSettings configura hosts bloqueados (runtime_blocked_hosts) para una extensión, browser.debugger.attach() se bloquea en todos los destinos con el error "Host access is restricted by policy." (incluso si los orígenes individuales están en runtime_allowed_hosts).
  • Políticas de captura de pantalla y DLP: Si la política empresarial DisableScreenshots inhabilita la captura de pantalla o si se aplican reglas de Prevención de pérdida de datos (DLP) al objetivo, browser.debugger.attach() falla con el error "Screenshot capture is restricted by policy.".

Conceptos y uso

Una vez que se adjunta, la API de browser.debugger te permite enviar comandos del Protocolo de herramientas para desarrolladores de Chrome (CDP) a un destino determinado. Explicar el CDP en detalle está fuera del alcance de esta documentación. Para obtener más información sobre el CDP, consulta la documentación oficial del CDP.

Destinos

Los destinos representan algo que se está depurando, lo que podría incluir una pestaña, un iframe o un worker. Cada destino se identifica con un UUID y tiene un tipo asociado (como iframe, shared_worker y muchos más).

Dentro de un destino, puede haber varios contextos de ejecución. Por ejemplo, los iframe del mismo proceso no obtienen un destino único, sino que se representan como contextos diferentes a los que se puede acceder desde un solo destino.

Dominios restringidos

Por motivos de seguridad, la API de browser.debugger no proporciona acceso a todos los dominios del protocolo de Herramientas para desarrolladores de Chrome. Los dominios disponibles son: 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 y WebAuthn.

Trabaja con fotogramas

No hay una asignación uno a uno de los fotogramas a los objetivos. Dentro de una sola pestaña, varios fotogramas del mismo proceso pueden compartir el mismo destino, pero usar un contexto de ejecución diferente. Por otro lado, se puede crear un destino nuevo para un iframe fuera del proceso.

Para adjuntar a todos los fotogramas, debes controlar cada tipo de fotograma por separado:

  • Espera el evento Runtime.executionContextCreated para identificar los nuevos contextos de ejecución asociados con los mismos marcos de proceso.

  • Sigue los pasos para adjuntar a destinos relacionados y, así, identificar los fotogramas fuera del proceso.

Después de conectarte a un destino, es posible que desees conectarte a otros destinos relacionados, incluidos los marcos secundarios fuera del proceso o los trabajadores asociados.

A partir de Chrome 125, la API de browser.debugger admite sesiones planas. Esto te permite agregar destinos adicionales como secundarios a tu sesión de depurador principal y enviarles mensajes sin necesidad de otra llamada a browser.debugger.attach. En cambio, puedes agregar una propiedad sessionId cuando llames a browser.debugger.sendCommand para identificar el destino secundario al que deseas enviar un comando.

Para adjuntar automáticamente a los marcos secundarios fuera del proceso, primero agrega un objeto de escucha para el evento Target.attachedToTarget:

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

Luego, habilita adjuntar automáticamente enviando el comando Target.setAutoAttach con la opción flatten establecida en true:

await browser