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 se conectar a uma ou mais guias para instrumentar a interação de rede, depurar JavaScript, modificar o DOM e o CSS e muito mais. Use a propriedade tabId Debuggee para segmentar guias com sendCommand e encaminhar eventos por tabId de callbacks onEvent.

Permissões

debugger

É necessário 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 protocolo Chrome DevTools (CDP, na sigla em inglês) para 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 do CDP.

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 muito mais.

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 em um único destino.

Domínios restritos

Por motivos de segurança, a API chrome.debugger não oferece acesso a todos os domínios de protocolo do Chrome DevTools. Os domínios disponíveis são: Acessibilidade, Auditorias, CacheStorage, Console, CSS, Banco de dados, Desenvolvedor, 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, uma nova segmentação pode ser criada para um iframe fora do processo.

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

• Ouça 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.

Anexar a destinos relacionados

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

A partir do Chrome 125, a API chrome.debugger oferece suporte a sessões simples. Isso permite que você adicione outros destinos como filhos à sua sessão principal do depurador e envie mensagens para eles sem precisar de outra chamada para chrome.debugger.attach. Em vez disso, é possível adicionar uma propriedade sessionId ao chamar chrome.debugger.sendCommand para identificar o destino filho para o qual 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 fixaçã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 fixação automática só é feita em 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 alvo associado a A resultaria na sessão também sendo anexada 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 do depurador do repositório chrome-extension-samples.

Tipos

Debuggee

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

Propriedades

• extensionId

  string opcional

  O ID da extensão que você pretende depurar. A anexação a uma página de segundo plano da extensão só é possível quando a chave de linha de comando --silent-debugger-extension-api é usada.

• tabId

  número opcional

  O ID da guia que você quer depurar.

• targetId

  string opcional

  O ID opaco do destino de depuração.

DebuggerSession

Chrome 125+

Identificador da sessão do depurador. É preciso especificar um dos seguintes campos: tabId, extensionId ou targetId. Além disso, é possível fornecer um sessionId opcional. Se o sessionId for especificado para argumentos enviados de onEvent, significa que o evento está vindo de uma sessão de protocolo filha na sessão raiz de depuração. Se o sessionId for especificado quando transmitido para sendCommand, ele terá como destino uma sessão de protocolo filha na sessão raiz do debuggee.

Propriedades

• extensionId

  string opcional

  O ID da extensão que você pretende depurar. A anexação a uma página de segundo plano da extensão só é possível quando a chave de linha de comando --silent-debugger-extension-api é usada.

• sessionId

  string opcional

  O ID opaco da sessão do protocolo das Chrome DevTools. Identifica uma sessão filha na sessão raiz identificada por tabId, extensionId ou targetId.

• tabId

  número opcional

  O ID da guia que você quer depurar.

• targetId

  string opcional

  O ID opaco do destino de depuração.

DetachReason

Chrome 44 e versões mais recentes

Motivo do encerramento da conexão.

Enumeração

"target_closed"

"canceled_by_user"

TargetInfo

Informações de depuração do destino

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

  número opcional

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

• título

  string

  Título da página de destino.

• tipo

  TargetInfoType

  Tipo de destino.

• url

  string

  URL de destino.

TargetInfoType

Chrome 44 e versões mais recentes

Tipo de destino.

Enumeração

"page"

"background_page"

"worker"

"Outros"

Métodos

attach()

Promessa

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

Anexa o depurador ao destino especificado.

Parâmetros

• target

  Debuggee

  Destino de depuração ao qual você quer se conectar.

• requiredVersion

  string

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

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 96 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

detach()

Promessa

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

Desconecta o depurador do destino especificado.

Parâmetros

• target

  Debuggee

  Destino de depuração do qual você quer se desconectar.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  Chrome 96 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getTargets()

Promessa

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

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

Parâmetros

• callback

  função opcional

  O parâmetro callback tem este formato:

  (result: TargetInfo[]) => void

  • resultado

    TargetInfo[]

    Matriz de objetos TargetInfo correspondentes aos destinos de depuração disponíveis.

Retorna

• Promise<TargetInfo[]>

  Chrome 96 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

sendCommand()

Promessa

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

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

Parâmetros

• target

  DebuggerSession

  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 para o método fornecido.

• callback

  função opcional

  O parâmetro callback tem este formato:

  (result?: object) => void

  • resultado

    objeto opcional

    Objeto JSON com a resposta. A estrutura da resposta varia de acordo com o nome do método e é definida pelo atributo "returns" da descrição do comando no protocolo de depuração remota.

Retorna

• Promise<object | undefined>

  Chrome 96 e versões mais recentes

  As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

Eventos

onDetach

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

É acionado quando o navegador encerra a sessão de depuração da guia. Isso acontece quando a guia está sendo fechada ou quando as Ferramentas do desenvolvedor do Chrome estão sendo invocadas para a guia anexada.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (source: Debuggee, reason: DetachReason) => void

  • source

    Debuggee

  • reason

    DetachReason

onEvent

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

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

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

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

  • source

    DebuggerSession

  • method

    string

  • params

    objeto opcional