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 e muito mais. Use a propriedade tabId
de Debuggee
para segmentar guias com sendCommand
e rotear eventos por tabId
de callbacks de 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 do Chrome DevTools
(CDP) para um determinado destino. Uma explicação detalhada sobre o CDP está fora do escopo
desta documentação. Para saber mais, 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 associado (como iframe
, shared_worker
e outros).
Dentro de um destino, pode haver vários contextos de execução. Por exemplo, iframes de 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 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
Trabalhar com frames
Não há um mapeamento de um para um de frames para destinos. Em uma única guia, vários frames de 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 de frame separadamente:
Detecte o evento
Runtime.executionContextCreated
para identificar novos contextos de execução associados aos mesmos frames de processo.Siga as etapas para anexar destinos relacionados e identificar frames fora do processo.
Anexar a destinos relacionados
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
oferece suporte a sessões simples. Isso
permite adicionar outros destinos como filhos à sessão principal do depurador e
enviar mensagens 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 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 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 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
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
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
Tipo de segmentação.
-
url
string
URL de destino.
TargetInfoType
Tipo de segmentação.
Tipo enumerado
"background_page"
Métodos
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
Anexa o depurador ao destino especificado.
Parâmetros
-
destino
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 recentePromessas 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()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
Remove o depurador do destino especificado.
Parâmetros
-
destino
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 recentePromessas 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()
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
Matriz de objetos TargetInfo correspondentes aos destinos de depuração disponíveis.
-
Retorna
-
Promise<TargetInfo[]>
Chrome 96 ou mais recentePromessas 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()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
Envia o comando especificado ao destino de depuração.
Parâmetros
-
destino
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 recentePromessas 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
-
callback
função
O parâmetro
callback
tem esta aparência:(source: Debuggee, reason: DetachReason) => void
-
source
-
reason
-
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
-
source
-
method
string
-
params
objeto opcional
-