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 uma ou mais guias para instrumentar a interação de rede, depurar JavaScript, alterar o DOM e o CSS e muito mais. Use a propriedade Debuggee tabId para segmentar guias com sendCommand e eventos de rota 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",
  ],
  ...
}

Restrições da política empresarial

Em dispositivos empresariais, algumas políticas podem restringir a anexação do depurador por extensões usando um modelo de tudo ou nada no momento da anexação (chrome.debugger.attach()):

  • Restrições de host: se a política empresarial ExtensionSettings configurar hosts bloqueados (runtime_blocked_hosts) para uma extensão, chrome.debugger.attach() será bloqueado em todos os destinos com o erro "Host access is restricted by policy." (mesmo que origens individuais estejam em runtime_allowed_hosts).
  • Políticas de captura de tela e DLP: Se a política empresarial DisableScreenshots desativar a captura de tela ou as regras de prevenção contra perda de dados (DLP, na sigla em inglês) forem aplicadas ao destino, chrome.debugger.attach() falhará com o erro "Screenshot capture is restricted by policy.".

Conceitos e uso

Depois de anexada, a chrome.debugger API permite enviar comandos do Chrome DevTools Protocol (CDP) para um determinado destino. A explicação detalhada do CDP 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, os 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 fornece acesso a todos os domínios do Chrome DevTools Protocol. Os domínios disponíveis são: Acessibilidade, Auditorias, CacheStorage, Console, CSS, Banco de dados, Depurador, DOM, DOMDebugger, DOMSnapshot, Emulação, Busca, IO, Entrada, Inspetor, Registro, Rede, Sobreposição, Página, Performance, Profiler, Runtime, Armazenamento, Destino, Rastreamento, WebAudio e WebAuthn.

Trabalhar com frames

Não há um mapeamento 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 de frame separadamente:

  • Ouça o evento Runtime.executionContextCreated para identificar novos contextos de execução associados a frames do mesmo processo.

  • Siga as etapas para anexar a destinos relacionados para 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 oferece suporte a sessões simples. Isso permite adicionar outros destinos como filhos à sessão principal do depurador e enviar mensagens a eles sem precisar de outra chamada para chrome.debugger.attach. Em vez disso, você pode adicionar uma propriedade sessionId ao chamar chrome.debugger.sendCommand para identificar o destino filho ao 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 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 }]
});

A anexação automática só é feita a frames que o destino conhece, que são limitados 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 entre origens), chamar Target.setAutoAttach para o destino associado a A resultaria na sessão também anexada a B. No entanto, isso não é recursivo. Portanto, Target.setAutoAttach também precisa ser chamado para B para anexar a sessão a C.

Exemplos

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

Tipos

Debuggee

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

Propriedades

  • extensionId

    string optional

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

  • tabId

    número optional

    O ID da guia que você pretende depurar.

  • targetId

    string optional

    O ID opaco do destino de depuração.

DebuggerSession

Chrome 125 e versões mais recentes

Identificador da sessão do depurador. É necessário especificar 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 filho na sessão de depuração raiz. Se sessionId for especificado quando passado para sendCommand, ele vai segmentar uma sessão de protocolo filho na sessão de depuração raiz.

Propriedades

  • extensionId

    string optional

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

  • sessionId

    string optional

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

  • tabId

    número optional

    O ID da guia que você pretende depurar.

  • targetId

    string optional

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

Propriedades

  • attached

    booleano

    Verdadeiro se o depurador já estiver anexado.

  • extensionId

    string optional

    O ID da extensão, definido se o tipo for "background_page".

  • faviconUrl

    string optional

    URL do favicon de destino.

  • id

    string

    ID de destino.

  • tabId

    número optional

    O ID da guia, definido se o tipo for "page".

  • title

    string

    Título da página de destino.

  • 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"

"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 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 de versões do protocolo pode ser acessada aqui.

Retorna

  • Promessa<void>

    Chrome 96 e versões mais recentes

    É resolvida quando a operação de anexação é bem-sucedida ou falha. A promessa é resolvida sem valor. Se a anexação falhar, a promessa será rejeitada.

detach()

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

Desanexa o depurador do destino especificado.

Parâmetros

  • target

    Debuggee

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

Retorna

  • Promessa<void>

    Chrome 96 e versões mais recentes

    É resolvida quando a operação de desanexação é bem-sucedida ou falha. A promessa é resolvida sem valor. Se a desanexação falhar, a promessa será rejeitada.

getTargets()

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

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

Retorna

  • Promessa<TargetInfo[]>

    Chrome 96 e versões mais recentes

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 ao 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 optional

    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 especificado.

Retorna

  • Promessa<object | undefined>

    Chrome 96 e versões mais recentes

    Corpo da resposta. Se ocorrer um erro ao postar a mensagem, a promessa será rejeitada.

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

Parâmetros

onEvent

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

Acionado 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