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 para instrumentar a interação de rede, depurar o JavaScript, modificar o DOM e o CSS etc. Use o tabId do depurador para segmentar guias com sendCommand e rotear eventos por tabId dos callbacks onEvent.

Permissões

debugger

É necessário declarar a permissão "debugger" no manifesto da extensão para usar a API.

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

Observação

Por motivos de segurança, a API chrome.debugger não fornece acesso a todos os domínios de protocolo do Chrome DevTools. Os domínios disponíveis são: Accessibility, Auditorias, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, DOMSnapshot, Emulação}DatabaseDatabase.WebAudioWebAuthn

Exemplos

Para testar essa API, instale o exemplo da API debugger no repositório chrome-extension-samples.

Tipos

Debuggee

Identificador do depurado. É necessário especificar tabId, extensionId ou targetId

Propriedades

  • extensionId

    string opcional

    O ID da extensão que você quer depurar. A anexação a uma página de segundo plano da extensão só é possível quando a chave da 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

Pendente

Identificador de sessão do depurador. Um dos tabId, extensionId ou targetId deve ser especificado. 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 filha na sessão de depurado raiz. Se sessionId for especificado quando transmitido para sendCommand, ele vai segmentar uma sessão de protocolo filha na sessão de depurado raiz.

Propriedades

  • extensionId

    string opcional

    O ID da extensão que você quer depurar. A anexação a uma página de segundo plano da extensão só é possível quando a chave da 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 dentro da 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 mais recente

Motivo do encerramento da conexão.

Tipo enumerado

"target_closed"

"canceled_by_user"

TargetInfo

Depurar informações do destino

Propriedades

  • sempre que o disco for anexado

    boolean

    Verdadeiro se o depurador já estiver anexado.

  • extensionId

    string opcional

    O código da extensão, definido se o tipo for 'background_page'.

  • faviconUrl

    string opcional

    URL do favicon de destino.

  • id

    string

    ID do destino.

  • tabId

    número opcional

    O ID da guia, definido se o tipo == 'page'.

  • title

    string

    Título da página de destino.

  • Tipo de segmentação.

  • url

    string

    URL de destino.

TargetInfoType

Chrome 44 ou mais recente

Tipo de segmentação.

Tipo enumerado

"background_page"

Métodos

attach()

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

Anexa o depurador ao destino especificado.

Parâmetros

  • destino

    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 com a versão secundária maior ou igual. Confira a lista das versões do protocolo aqui.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

detach()

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

Remove o depurador do destino especificado.

Parâmetros

  • destino

    Depurado

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

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado 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 optional

    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<TargetInfo[]>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

sendCommand()

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

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

Parâmetros

  • destino

    DebuggerSession

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

  • callback

    função optional

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

Retorna

  • Promise<object|undefined>

    Chrome 96 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

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 destino de depuração emitir 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