chrome.debugger

Descripción

La API de chrome.debugger sirve 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 Debuggee propiedad tabId para segmentar pestañas con sendCommand y enrutar eventos por tabId desde onEvent devoluciones de llamada.

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 conexión (chrome.debugger.attach()):

  • Restricciones de host: Si la política empresarial ExtensionSettings configura hosts bloqueados (runtime_blocked_hosts) para una extensión, chrome.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 se aplican reglas de Prevención de pérdida de datos (DLP) al destino, chrome.debugger.attach() falla con el error "Screenshot capture is restricted by policy.".

Conceptos y uso

Una vez adjunta, la API chrome.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 trabajador. Cada destino se identifica con un UUID y tiene un tipo asociado (como iframe, shared_worker y mucho más).

Dentro de un destino, puede haber varios contextos de ejecución. Por ejemplo, los iframes 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 chrome.debugger no proporciona acceso a todos los dominios del Protocolo de herramientas para desarrolladores de Chrome. Los dominios disponibles son: Accesibilidad, Auditorías, CacheStorage, Consola, CSS, Base de datos, Depurador, DOM, DOMDebugger, DOMSnapshot, Emulación, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio y WebAuthn.

Trabaja con marcos

No hay una asignación de uno a uno de marcos a destinos. Dentro de una sola pestaña, varios marcos 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 todos los marcos, debes controlar cada tipo de marco por separado:

  • Escucha el evento Runtime.executionContextCreated para identificar los contextos de ejecución nuevos asociados con los marcos del mismo proceso.

  • Sigue los pasos para adjuntar destinos relacionados para identificar marcos 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 chrome.debugger admite sesiones planas. Esto te permite agregar destinos adicionales como elementos secundarios a tu sesión de depurador principal y enviarles mensajes sin necesidad de otra llamada a chrome.debugger.attach. En cambio, puedes agregar una propiedad sessionId cuando llamas a chrome.debugger.sendCommand para identificar el destino secundario al que deseas enviar un comando.

Para adjuntar automáticamente marcos secundarios fuera del proceso, primero agrega un objeto de escucha para el evento 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");
  }
});

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

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

La conexión automática solo se conecta a los marcos que conoce el destino, que se limita a los marcos que son elementos secundarios inmediatos de un marco asociado a él. Por ejemplo, con la jerarquía de marcos A -> B -> C (donde todos son de origen cruzado), llamar a Target.setAutoAttach para el destino asociado con A haría que la sesión también se adjunte a B. Sin embargo, esto no es recursivo, por lo que también se debe llamar a Target.setAutoAttach para que B adjunte la sesión a C.

Ejemplos

Para probar esta API, instala el ejemplo de la API de depurador del repositorio chrome-extension-samples.

Tipos

Debuggee

Identificador de depuración. Se debe especificar tabId, extensionId o targetId.

Propiedades

  • extensionId

    string opcional

    Es el ID de la extensión que deseas depurar. Solo es posible adjuntar una página en segundo plano de la extensión cuando se usa el parámetro de línea de comandos --silent-debugger-extension-api.

  • tabId

    número opcional

    Es el ID de la pestaña que deseas depurar.

  • targetId

    string opcional

    Es el ID opaco del destino de depuración.

DebuggerSession

Chrome 125+

Identificador de la sesión del depurador. Se debe especificar tabId, extensionId o targetId. Además, se puede proporcionar un sessionId opcional. Si se especifica sessionId para los argumentos enviados desde onEvent, significa que el evento proviene de una sesión de protocolo secundaria dentro de la sesión de depuración raíz. Si se especifica sessionId cuando se pasa a sendCommand, se segmenta una sesión de protocolo secundaria dentro de la sesión de depuración raíz.

Propiedades

  • extensionId

    string opcional

    Es el ID de la extensión que deseas depurar. Solo es posible adjuntar una página en segundo plano de la extensión cuando se usa el parámetro de línea de comandos --silent-debugger-extension-api.

  • sessionId

    string opcional

    Es el ID opaco de la sesión del Protocolo de herramientas para desarrolladores de Chrome. Identifica una sesión secundaria dentro de la sesión raíz identificada por tabId, extensionId o targetId.

  • tabId

    número opcional

    Es el ID de la pestaña que deseas depurar.

  • targetId

    string opcional

    Es el ID opaco del destino de depuración.

DetachReason

Chrome 44+

Motivo de la inhabilitación de la conexión.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Información del destino de depuración

Propiedades

  • se conecte el disco

    booleano

    Verdadero si el depurador ya está conectado.

  • extensionId

    string opcional

    El ID de la extensión, definido si el tipo es "background_page".

  • faviconUrl

    string opcional

    URL del ícono de página de destino.

  • id

    string

    ID de destino.

  • tabId

    número opcional

    El ID de la pestaña, definido si el tipo es "page".

  • título

    string

    Título de la página de destino.

  • Tipo de destino.

  • url

    string

    URL del destino.

TargetInfoType

Chrome 44+

Tipo de destino.

Enum

"page"

"background_page"

"worker"

"other"

Métodos

attach()

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

Adjunta el depurador al destino determinado.

Parámetros

  • objetivo

    Debuggee

    Destino de depuración al que deseas adjuntar.

  • requiredVersion

    string

    Versión requerida del protocolo de depuración ("0.1"). Solo se puede adjuntar al elemento depurado con la versión principal coincidente y la versión secundaria mayor o igual. La lista de las versiones del protocolo se puede obtener aquí.

Muestra

  • Promise<void>

    Chrome 96+

    Se resuelve una vez que la operación de conexión se realiza correctamente o falla. La promesa se resuelve sin valor. Si falla la conexión, se rechazará la promesa.

detach()

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

Desconecta el depurador del destino determinado.

Parámetros

  • objetivo

    Debuggee

    Destino de depuración del que deseas desconectar.

Muestra

  • Promise<void>

    Chrome 96+

    Se resuelve una vez que la operación de desconexión se realiza correctamente o falla. La promesa se resuelve sin valor. Si falla la desconexión, se rechazará la promesa.

getTargets()

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

Muestra la lista de destinos de depuración disponibles.

Muestra

sendCommand()

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

Envía el comando determinado al destino de depuración.

Parámetros

  • objetivo

    DebuggerSession

    Destino de depuración al que deseas enviar el comando.

  • método

    string

    Nombre del método. Debe ser uno de los métodos definidos por el protocolo de depuración remota.

  • commandParams

    objeto opcional

    Objeto JSON con parámetros de solicitud. Este objeto debe cumplir con el esquema de parámetros de depuración remota para el método determinado.

Muestra

  • Promise<object | undefined>

    Chrome 96+

    Cuerpo de la respuesta. Si se produce un error mientras se publica el mensaje, se rechazará la promesa.

Eventos

onDetach

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

Se activa cuando el navegador finaliza la sesión de depuración de la pestaña. Esto sucede cuando se cierra la pestaña o se invoca a las Herramientas para desarrolladores de Chrome para la pestaña adjunta.

Parámetros

onEvent

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

Se activa cada vez que el destino de depuración emite un evento de instrumentación.

Parámetros

  • callback

    función

    El parámetro callback tiene el siguiente aspecto: 

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