chrome.debugger

Descrição

A API chrome.debugger serve como um transporte alternativo para o protocolo de depuração remota do Google Chrome. Use chrome.debugger para anexar a uma ou mais guias e instrumentar a interação de rede, depurar o JavaScript, modificar o DOM e o CSS e muito mais. Use a propriedade Debuggee tabId para segmentar guias com sendCommand e rotear eventos por tabId a partir 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 anexado, a API chrome.debugger permite que você envie o protocolo Chrome DevTools (CDP) para um determinado destino. Explicar o CDP em detalhes está fora do escopo documentação. Para saber mais sobre o CDP, consulte a documentação oficial do CDP.

Destinos

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

Dentro de um destino, pode haver vários contextos de execução, por exemplo, o mesmo os iframes de processo não têm um destino único, mas são representados como contextos diferentes que podem ser acessados de um único alvo.

Domínios restritos

Por motivos de segurança, a API chrome.debugger não fornece acesso a todas as Chrome DevTools de protocolo. Os domínios disponíveis são: Acessibilidade, Auditorias, CacheStorage, Console, CSS, Banco de dados, Debugger, DOM, DOMDebugger e DOMSnapshot, Emulação, Buscar, E/S, Entrada, Inspetor, Registro, Rede, Sobreposição, Página, Performance, Profiler, Ambiente de execução, Armazenamento, Destino, Rastreamento, WebAudio e WebAuthn.

Trabalhar com frames

Não há um mapeamento de um para um entre os frames e os destinos. Em uma única guia, vários frames de processo iguais podem ter o mesmo destino, contexto de execução. Por outro lado, uma nova meta pode ser criado para um iframe fora do processo.

Para anexar a todos os frames, você precisa processar cada tipo de frame separadamente:

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

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

Depois de se conectar a um destino, você pode conectar-se 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 à sessão principal do depurador e enviar uma mensagem sem precisar chamar chrome.debugger.attach. Em vez disso, é possível adicionar uma propriedade sessionId ao chamar chrome.debugger.sendCommand para identifique o destino filho para o qual gostaria de 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 anexaçã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 }]
});

Exemplos

Para testar essa API, instale o exemplo da API do depurador disponível em chrome-extension-samples repositório de dados.

Tipos

Debuggee

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

Propriedades

  • extensionId

    string opcional

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

  • tabId

    número opcional

    O ID da guia que você pretende depurar.

  • targetId

    string opcional

    O ID opaco do destino de depuração.

DebuggerSession

Chrome 125 ou versões mais recentes

Identificador de sessão do depurador. É necessário especificar um 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 vem de uma sessão de protocolo filho na sessão do depurado raiz. Se sessionId for especificado quando transmitido para sendCommand, ele será direcionado a uma sessão de protocolo filho na sessão do depurado raiz.

Propriedades

  • extensionId

    string opcional

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

  • sessionId

    string opcional

    O ID opaco da sessão do protocolo do 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ê pretende depurar.

  • targetId

    string opcional

    O ID opaco do destino de depuração.

DetachReason

Chrome 44 ou superior

Motivo do encerramento da conexão.

Enumeração

"target_closed"

"canceled_by_user"

TargetInfo

Depurar as informações 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 de segmentação.

  • url

    string

    URL de destino.

TargetInfoType

Chrome 44 ou superior

Tipo de segmentação.

Enumeração

"página"

"background_page"

"trabalhador"

"outro"

Métodos

attach()

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

Anexa o depurador ao destino especificado.

Parâmetros

  • target

    Depurado

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

  • requiredVersion

    string

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

detach()

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

Separa o depurador do destino especificado.

Parâmetros

  • target

    Depurado

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 esta aparência: 

    (result: TargetInfo[]) => void

    • resultado

      TargetInfo[]

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

Retorna

  • Promise&lt;TargetInfo[]&gt;

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

sendCommand()

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

Envia o comando fornecido para o alvo da depuração.

Parâmetros

  • Destino de depuração para 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 da depuração remota para o método especificado.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (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 pelos "returns" da descrição do comando no protocolo de depuração remota.

Retorna

  • Promise&lt;object | indefinido>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 o Chrome DevTools está sendo invocado para a guia anexada.

Parâmetros

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 esta aparência: 

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