chrome.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 adjuntarlo a una o más pestañas a fin de instrumentar la interacción de red, depurar JavaScript, mutar el DOM y la CSS, y mucho más. Usa la propiedad tabId de Debuggee para segmentar las pestañas con sendCommand y los eventos de ruta por tabId a partir de devoluciones de llamada de onEvent.

Permisos

debugger

Para usar esta API, debes declarar el permiso "debugger" en el manifiesto de tu extensión.

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

Conceptos y uso

Una vez adjuntada, la API de chrome.debugger te permite enviar el protocolo de Herramientas para desarrolladores de Chrome (CDP) a un objetivo determinado. Explicar en profundidad la CDP está fuera del alcance para esta documentación. Para obtener más información sobre CDP, consulta la documentación oficial de CDP.

Destinos

Los objetivos representan algo que se está depurando, esto podría incluir una pestaña, un iframe o un trabajador. Cada destino se identifica mediante un UUID y tiene un (por ejemplo, iframe, shared_worker y otros).

Dentro de un destino, puede haber varios contextos de ejecución, por ejemplo, el mismo los iframes del proceso no tienen un destino único, sino que se representan contextos diferentes a los que se puede acceder desde un mismo objetivo.

Dominios restringidos

Por motivos de seguridad, la API de chrome.debugger no proporciona acceso a todas las Herramientas para desarrolladores de Chrome Dominios de protocolo. Los dominios disponibles son: accesibilidad, Audits, CacheStorage, Console CSS, Base de datos, Depurador, DOM, DOMDebugger, DOMSnapshot: Emulation, Fetch, IO, Entrada, Inspector, Registro, Red, Superposición, Página, Rendimiento, Generador de perfiles, Entorno de ejecución, Almacenamiento, Destino, Seguimiento WebAudio y WebAuthn.

Cómo trabajar con marcos

No existe una asignación uno a uno de los fotogramas a los objetivos. En una sola pestaña, varios marcos de un mismo proceso pueden compartir el mismo objetivo, pero usar un contexto de ejecución. Por otro lado, un nuevo objetivo puede ser para un iframe fuera del proceso.

Para adjuntar a todos los marcos, debes controlar cada tipo de marco por separado:

  • Escucha el evento Runtime.executionContextCreated para identificar un evento nuevo. de ejecución asociados con los mismos marcos de proceso.

  • Sigue los pasos para vincular destinos relacionados a lo siguiente: identificar marcos fuera del proceso.

Después de establecer la conexión con un destino, es posible que desees conectarte con 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. Esta te permite agregar destinos adicionales como elementos secundarios a tu sesión principal de depurador y envíales un mensaje sin necesidad de llamar a chrome.debugger.attach. En cambio, puedes agregar una propiedad sessionId cuando llames a chrome.debugger.sendCommand para identifica el destino secundario al que deseas enviar un comando.

Para adjuntar automáticamente a los fotogramas 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. Para ello, envía el comando Target.setAutoAttach 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 }]
});

Ejemplos

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

Tipos

Debuggee

Es el identificador del elemento depurado. Se debe especificar tabId, extensionId o targetId

Propiedades

  • extensionId

    string opcional

    El ID de la extensión que pretendes depurar. Solo se puede adjuntar a una página en segundo plano de una extensión cuando se usa el interruptor 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

    El ID opaco del objetivo de depuración.

DebuggerSession

Chrome 125 y versiones posteriores

Es el identificador de la sesión de Debugger. 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 secundario dentro de la sesión raíz de depuración. Si se especifica sessionId cuando se pasa a sendCommand, se orienta a una sesión de protocolo secundario dentro de la sesión raíz de depuración.

Propiedades

  • extensionId

    string opcional

    El ID de la extensión que pretendes depurar. Solo se puede adjuntar a una página en segundo plano de una extensión cuando se usa el interruptor de línea de comandos --silent-debugger-extension-api.

  • sessionId

    string opcional

    Es el ID opaco de la sesión del protocolo de las 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

    El ID opaco del objetivo de depuración.

DetachReason

Chrome 44 y versiones posteriores

Motivo de la finalización de la conexión.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Depura la información del destino

Propiedades

  • se conecte el disco

    boolean

    Es verdadero si ya se adjuntó el depurador.

  • extensionId

    string opcional

    El ID de la extensión, definido si el tipo = “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 == 'page'.

  • título

    string

    Título de la página de destino.

  • Tipo de objetivo.

  • url

    string

    URL de destino.

TargetInfoType

Chrome 44 y versiones posteriores

Tipo de objetivo.

Enum

“página”

"background_page"

"trabajador"

“otro”

Métodos

attach()

Promesa 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Adjunta el depurador al destino determinado.

Parámetros

  • objetivo

    Depurado

    Destino de depuración al que quieres adjuntar datos.

  • requiredVersion

    string

    Versión requerida del protocolo de depuración ("0.1"). Solo se puede adjuntar al elemento depurado con una versión principal que coincida y una versión secundaria superior o igual. Aquí puedes obtener la lista de las versiones del protocolo.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

detach()

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

Desconecta el depurador del destino determinado.

Parámetros

  • objetivo

    Depurado

    Destino de depuración del que quieres desconectarte.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

getTargets()

Promesa 
chrome.debugger.getTargets(
  callback?: function,
)

Muestra la lista de objetivos de depuración disponibles.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: TargetInfo[]) => void

    • resultado

      TargetInfo[]

      Es el array de objetos TargetInfo que corresponden a los objetivos de depuración disponibles.

Muestra

  • Promise&lt;TargetInfo[]&gt;

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

sendCommand()

Promesa 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Envía un comando dado al destino de depuración.

Parámetros

  • objetivo

    DebuggerSession

    Destino de depuración al que deseas enviar el comando

  • method

    string

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

  • commandParams

    objeto opcional

    Un 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.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result?: object) => void

    • resultado

      objeto opcional

      JSON con la respuesta. La estructura de la respuesta varía según el nombre del método y se define mediante los “retornos” de la descripción del comando en el protocolo de depuración remota.

Muestra

  • Promise&lt;object | indefinido>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.

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 objetivo de depuración genera un evento de instrumentación.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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