chrome.debugger

Descrição

A API chrome.debugger serve como um transporte alternativo para o protocolo de depuração remota do Chrome. Use chrome.debugger para anexar a uma ou mais guias e instrumentar a interação de rede, depurar JavaScript, mudar o DOM e o CSS e muito mais. Use a propriedade Debuggee tabId para segmentar guias com sendCommand e rotear eventos por tabId de callbacks onEvent.

Permissões

debugger

Você precisa declarar a permissão "debugger" no manifesto da extensão para usar essa API.

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

Conceitos e uso

Depois de anexada, a API chrome.debugger permite enviar comandos do Chrome DevTools Protocol (CDP) a um determinado destino. Explicar o CDP em detalhes está fora do escopo desta documentação. Para saber mais sobre o CDP, consulte a documentação oficial.

Destinos

Os destinos representam algo que está sendo depurado, como uma guia, um iframe ou um worker. Cada destino é identificado por um UUID e tem um tipo associado (como iframe, shared_worker e outros).

Em um destino, pode haver vários contextos de execução. Por exemplo, iframes do mesmo processo não recebem um destino exclusivo, mas são representados como contextos diferentes que podem ser acessados de um único destino.

Domínios restritos

Por motivos de segurança, a API chrome.debugger não oferece acesso a todos os domínios do protocolo do Chrome DevTools. Os domínios disponíveis são: Acessibilidade, Auditorias, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio e WebAuthn.

Trabalhar com frames

Não há um mapeamento de um para um de frames para destinos. Em uma única guia, vários frames do mesmo processo podem compartilhar o mesmo destino, mas usar um contexto de execução diferente. Por outro lado, um novo destino pode ser criado para um iframe fora do processo.

Para anexar a todos os frames, é necessário processar cada tipo separadamente:

  • Aguarde o evento Runtime.executionContextCreated para identificar novos contextos de execução associados aos mesmos frames de processo.

  • Siga as etapas para anexar a destinos relacionados e identificar frames fora do processo.

Depois de se conectar a um destino, talvez você queira se conectar a outros destinos relacionados, incluindo frames filhos fora do processo ou workers associados.

A partir do Chrome 125, a API chrome.debugger é compatível com sessões simples. Isso permite adicionar outros destinos como filhos à sua sessão principal do depurador e enviar mensagens para eles sem precisar de outra chamada para chrome.debugger.attach. Em vez disso, adicione uma propriedade sessionId ao chamar chrome.debugger.sendCommand para identificar o destino secundário a que você quer enviar um comando.

Para anexar automaticamente a frames filhos fora do processo, primeiro adicione um listener para o 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");   } });

Em seguida, ative a conexão automática enviando o comando Target.setAutoAttach com a opção flatten definida como true:

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

A vinculação automática só se conecta a frames que o destino conhece, o que é limitado a frames que são filhos imediatos de um frame associado a ele. Por exemplo, com a hierarquia de frames A -> B -> C (em que todos são de origem cruzada), chamar Target.setAutoAttach para o destino associado a A também anexaria a sessão a B. No entanto, isso não é recursivo. Portanto, Target.setAutoAttach também precisa ser chamado para que B anexe a sessão a C.

Exemplos

Para testar essa API, instale o exemplo da API de depurador do repositório chrome-extension-samples (link em inglês).

Tipos

Debuggee

Identificador do depurado. É preciso especificar tabId, extensionId ou targetId

Propriedades

  • extensionId

    string opcional

    O ID da extensão que você quer depurar. Só é possível anexar a uma página em segundo plano de extensão quando a opção de linha de comando --silent-debugger-extension-api é usada.

  • tabId

    number optional

    O ID da guia que você quer depurar.

  • targetId

    string opcional

    O ID opaco do destino de depuração.

DebuggerSession

Chrome 125 ou mais recente

Identificador da sessão do depurador. É preciso especificar um dos seguintes campos: tabId, extensionId ou targetId. Além disso, um sessionId opcional pode ser fornecido. Se "sessionId" for especificado para argumentos enviados de onEvent, isso significa que o evento está vindo de uma sessão de protocolo secundária dentro da sessão raiz do depurador. Se "sessionId" for especificado ao ser transmitido para sendCommand, ele vai segmentar uma sessão de protocolo secundária na sessão raiz do depurador.

Propriedades

  • extensionId

    string opcional

    O ID da extensão que você quer depurar. Só é possível anexar a uma página em segundo plano de extensão quando a opção de linha de comando --silent-debugger-extension-api é usada.

  • sessionId

    string opcional

    O ID opaco da sessão do Chrome DevTools Protocol. Identifica uma sessão secundária na sessão raiz identificada por tabId, extensionId ou targetId.

  • tabId

    number optional

    O ID da guia que você quer depurar.

  • targetId

    string opcional

    O ID opaco do destino de depuração.

DetachReason

Chrome 44 ou mais recente

Motivo do término da conexão.

Enumeração

"target_closed"

"canceled_by_user"

TargetInfo

Informações de destino de depuração

Propriedades

  • sempre que o disco for anexado

    booleano

    Verdadeiro se o depurador já estiver anexado.

  • extensionId

    string opcional

    O ID da extensão, definido se type = "background_page".

  • faviconUrl

    string opcional

    URL do favicon de destino.

  • ID

    string

    ID de destino.

  • tabId

    number optional

    O ID da guia, definido se type == "page".

  • título

    string

    Título da página de destino.

  • Tipo de destino.

  • url

    string

    URL de destino.

TargetInfoType

Chrome 44 ou mais recente

Tipo de destino.

Enumeração

"page"

"background_page"

"worker"

"other"

Métodos

attach()

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

Anexa o depurador ao destino especificado.

Parâmetros

  • target

    Debuggee

    Destino de depuração a que você quer anexar.

  • requiredVersion

    string

    Versão necessária do protocolo de depuração ("0.1"). Só é possível anexar ao debuggee com a mesma versão principal e uma versão secundária maior ou igual. A lista de versões do protocolo pode ser acessada aqui.

Retorna

  • Promise<void>

    Chrome 96+

detach()

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

Desvincula o depurador do destino especificado.

Parâmetros

  • target

    Debuggee

    Alvo de depuração que você quer remover.

Retorna

  • Promise<void>

    Chrome 96+

getTargets()

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

Retorna a lista de destinos de depuração disponíveis.

Retorna

sendCommand()

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

Envia o comando especificado para o destino de depuração.

Parâmetros

  • Destino de depuração para o qual você quer enviar o comando.

  • method

    string

    Nome do método. Precisa ser um dos métodos definidos pelo protocolo de depuração remota.

  • commandParams

    objeto opcional

    Objeto JSON com parâmetros de solicitação. Esse objeto precisa estar em conformidade com o esquema de parâmetros de depuração remota do método especificado.

Retorna

  • Promise<object | undefined>

    Chrome 96+

Eventos

onDetach

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

Disparado quando o navegador encerra a sessão de depuração da guia. Isso acontece quando a guia está sendo fechada ou quando o Chrome DevTools está sendo invocado para a guia anexada.

Parâmetros

onEvent

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

Disparado sempre que o evento de instrumentação de problemas de destino de depuração.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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