Descripción
La API de chrome.debugger
sirve como transporte alternativo para el protocolo de depuración remota de Chrome. Usa chrome.debugger
para adjuntar a una o más pestañas a fin de instrumentar la interacción de red, depurar JavaScript, mutar el DOM y el CSS, y mucho más. Usa la propiedad tabId
de Debuggee
para segmentar pestañas con sendCommand
y enrutar eventos mediante 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 adjunta, la API de chrome.debugger
te permite enviar comandos del protocolo de Herramientas para desarrolladores de Chrome (CDP) a un destino determinado. La explicación detallada de CDP está fuera del alcance de esta documentación. Para obtener más información sobre CDP, consulta la documentación oficial de CDP.
Destinos
Los destinos representan un elemento que se está depurando, como una pestaña, un iframe o un trabajador. Cada destino se identifica mediante un UUID y tiene un tipo asociado (como iframe
, shared_worker
y otros).
Dentro de un destino, puede haber varios contextos de ejecución. Por ejemplo, los iframes del mismo proceso no tienen un objetivo ú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 de protocolo de las Herramientas para desarrolladores de Chrome. Los dominios disponibles son: Accessibility,
Audits, CacheStorage, Console,
CSS, Database, WebDebugger, DOMDebugger, DOMSnapshot,EmulationWebAudioWebAuthn
Cómo trabajar con marcos
No hay una asignación de uno a uno de los fotogramas a los objetivos. En una sola pestaña, varios fotogramas del proceso pueden compartir el mismo objetivo, pero usar un contexto de ejecución diferente. Por otro lado, se puede crear un destino nuevo para un iframe fuera del proceso.
Para adjuntarlo a todos los marcos, debes controlar cada tipo de marco por separado:
Escucha el evento
Runtime.executionContextCreated
para identificar nuevos contextos de ejecución asociados con los mismos fotogramas del proceso.Sigue los pasos para vincularlos a objetivos relacionados y, así, identificar fotogramas fuera del proceso.
Adjuntar a objetivos relacionados
Después de conectarte con un destino, es posible que quieras conectarte a otros objetivos relacionados, incluidos los marcos secundarios fuera del proceso o los trabajadores asociados.
A partir de Chrome 125, la API de chrome.debugger
admite sesiones fijas. De esta manera, puedes agregar destinos adicionales como elementos secundarios a tu sesión principal del depurador y enviarles mensajes sin necesidad de otra llamada a chrome.debugger.attach
. En su lugar, puedes agregar una propiedad sessionId
cuando llames a chrome.debugger.sendCommand
para identificar el destino secundario al que deseas enviar un comando.
Para adjuntar automáticamente a 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 mediante el envío del 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 del depurador del repositorio chrome-extension-samples.
Tipos
Debuggee
Es el identificador del elemento depurado. Se debe especificar tabId, extensionId o targetId
Propiedades
-
extensionId
cadena opcional
Es el ID de la extensión que quieres depurar. La conexión a una página en segundo plano de una extensión solo es posible cuando se usa el cambio de línea de comandos
--silent-debugger-extension-api
. -
tabId
número opcional
El ID de la pestaña que deseas depurar.
-
targetId
cadena opcional
Es el ID opaco del destino de la depuración.
DebuggerSession
Es el identificador de sesión del depurador. Se debe especificar uno de los campos 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 orienta a una sesión de protocolo secundaria dentro de la sesión raíz de depuración.
Propiedades
-
extensionId
cadena opcional
Es el ID de la extensión que quieres depurar. La conexión a una página en segundo plano de una extensión solo es posible cuando se usa el cambio de línea de comandos
--silent-debugger-extension-api
. -
sessionId
cadena opcional
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
El ID de la pestaña que deseas depurar.
-
targetId
cadena opcional
Es el ID opaco del destino de la depuración.
DetachReason
Motivo de cancelación de la conexión.
Enum
"target_closed"
"canceled_by_user"
TargetInfo
Depurar información de destino
Propiedades
-
se conecte el disco
boolean
Es verdadero si ya se adjuntó el depurador.
-
extensionId
cadena opcional
El ID de la extensión, definido si tipo = 'background_page'.
-
faviconUrl
cadena opcional
URL del ícono de página de destino.
-
id
cadena
ID de destino.
-
tabId
número opcional
El ID de pestaña, definido si tipo == 'page'.
-
title
cadena
Es el título de la página de destino.
-
Tipo
Tipo de objetivo.
-
url
cadena
URL de destino.
TargetInfoType
Tipo de objetivo.
Enum
"background_page"
"worker"
Métodos
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Adjunta el depurador al destino determinado.
Parámetros
-
destino
Destino de depuración al que quieres conectar
-
requiredVersion
cadena
Versión requerida del protocolo de depuración ("0.1"). Solo se puede adjuntar al elemento depurado con una versión principal coincidente y una versión secundaria superior o igual. Puedes obtener la lista de las versiones del protocolo aquí.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Desconecta el depurador del destino determinado.
Parámetros
-
destino
Destino de depuración del que quieres desconectar.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
Muestra la lista de destinos de depuración disponibles.
Parámetros
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: TargetInfo[]) => void
-
resultado
Es el array de objetos TargetInfo que corresponden a los destinos de depuración disponibles.
-
Devuelve
-
Promise<TargetInfo[]>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Envía el comando al destino de depuración.
Parámetros
-
destino
El destino de depuración al que quieres enviar el comando.
-
method
cadena
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.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result?: object) => void
-
resultado
objeto opcional
un objeto JSON con la respuesta. La estructura de la respuesta varía según el nombre del método y se define mediante el atributo “returns” de la descripción del comando en el protocolo de depuración remota.
-
Devuelve
-
Promise<object | undefined>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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 invocan las Herramientas para desarrolladores de Chrome para la pestaña adjunta.
Parámetros
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(source: Debuggee, reason: DetachReason) => void
-
source
-
Reason
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
Se activa cuando el objetivo de depuración emite un evento de instrumentación.
Parámetros
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
cadena
-
params
objeto opcional
-