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 conectarte a una o más pestañas para instrumentar la interacción de red, depurar JavaScript, mutar el DOM y el CSS, y mucho más. Usa la propiedad Debuggee tabId para segmentar pestañas con sendCommand y enrutar eventos por tabId desde las 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 conectada, la API de chrome.debugger te permite enviar comandos del protocolo de DevTools de Chrome (CDP) a un destino determinado. Explicar la CDP en detalle está fuera del alcance de esta documentación. Para obtener más información sobre la CDP, consulta la documentación oficial de la CDP.

Destinos

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

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

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, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, 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 uno a uno de los fotogramas a los objetivos. Dentro de una sola pestaña, varios fotogramas del mismo proceso pueden compartir el mismo objetivo, pero usar un contexto de ejecución diferente. Por otro lado, se puede crear un objetivo 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 marcos de proceso.

  • Sigue los pasos para adjuntarte a objetivos relacionados y así identificar fotogramas fuera del proceso.

Después de conectarte a un destino, te recomendamos que te conectes a otros destinos relacionados, incluidos los subprocesos 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 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 objetivo secundario al que deseas enviar un comando.

Para adjuntarte 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 el conexión automática enviando 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 }]
});

La vinculación automática solo se vincula a los marcos que el destino conoce, lo que se limita a los marcos que son elementos secundarios inmediatos de un marco asociado con él. Por ejemplo, con la jerarquía de marcos A -> B -> C (donde todos son de origen cruzado), llamar a Target.setAutoAttach para el objetivo asociado con A provocaría que la sesión también se adjuntara 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 del depurador desde el 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 deseas depurar. Solo es posible adjuntarse a una página en segundo plano de la extensión cuando se usa el interruptor 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

    El ID opaco del destino de depuración.

DebuggerSession

Chrome 125 y versiones posteriores

Es el identificador de la sesión del depurador. Se debe especificar uno de los siguientes valores: 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 del depurador raíz. Si se especifica sessionId cuando se pasa a sendCommand, se segmenta a una sesión de protocolo secundaria dentro de la sesión del depurado raíz.

Propiedades

  • extensionId

    cadena opcional

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

  • sessionId

    cadena opcional

    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

    El ID de la pestaña que deseas depurar.

  • targetId

    cadena opcional

    El ID opaco del destino de depuración.

DetachReason

Chrome 44 y versiones posteriores

Es el motivo por el que se inhabilitó la conexión.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

Información del destino de depuración

Propiedades

  • se conecte el disco

    booleano

    Es verdadero si el depurador ya está adjunto.

  • extensionId

    cadena opcional

    El ID de la extensión, definido si type = 'background_page'.

  • faviconUrl

    cadena opcional

    Es la 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 type == 'page'.

  • título

    string

    Es el 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

"page"

"background_page"

"worker"

"other"

Métodos

attach()

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

Adjunta el depurador al destino determinado.

Parámetros

  • Es el destino de depuración al que deseas conectarte.

  • requiredVersion

    string

    Versión obligatoria del protocolo de depuración ("0.1"). Solo se puede conectar al objeto de depuración con una versión principal coincidente y una versión secundaria mayor 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

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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()

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

Desconecta el depurador del destino determinado.

Parámetros

  • Es el destino de depuración del que deseas desconectarte.

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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()

Promesa 
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

      TargetInfo[]

      Es un array de objetos TargetInfo que corresponden a los destinos de depuración disponibles.

Muestra

  • Promise<TargetInfo[]>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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()

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

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

Parámetros

  • objetivo

    DebuggerSession

    Es el 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

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

  • callback

    función opcional

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

    (result?: object) => void

    • resultado

      objeto opcional

      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 "devuelve" de la descripción del comando en el protocolo de depuración remota.

Muestra

  • Promesa<objeto | undefined>

    Chrome 96 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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 ocurre cuando se cierra la pestaña o se invocan 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 se produce un evento de instrumentación de problemas de destino de depuración.

Parámetros

  • callback

    función

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

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