Depurar extensões

As extensões podem acessar as mesmas Chrome DevTools que as páginas da Web. Para se tornar um especialista em depuração de extensões, você precisará saber como localizar registros e erros dos diferentes componentes da extensão. Este tutorial fornece técnicas fundamentais para depurar sua extensão.

Antes de começar

Este guia pressupõe que você tenha experiência básica em desenvolvimento na Web. Recomendamos a leitura Princípios básicos de desenvolvimento para uma introdução ao fluxo de trabalho de desenvolvimento de extensões. Projetar a interface do usuário apresenta uma introdução ao usuário da interface de usuário disponíveis nas extensões.

Interromper a extensão

Este tutorial quebrará um componente de extensão por vez e demonstrará como corrigi-lo. Lembre-se de desfazer os bugs introduzidos em uma seção antes de continuar para a próxima. Comece fazendo o download do exemplo de cor corrompida (link em inglês) no GitHub.

Depurar o manifesto

Primeiro, vamos quebrar o arquivo de manifesto mudando a chave "version" para "versions":

manifest.json:

{
  "name": "Broken Background Color",
  "version": "1.0",
  "versions": "1.0",
  "description": "Fix an Extension!",
  ...
}

Agora tente carregar a extensão localmente. Você verá uma caixa de diálogo de erro apontando para o problema:

Failed to load extension
Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536.
Could not load manifest.

Caixa de diálogo de erro de chave de manifesto inválida.

Quando uma chave de manifesto é inválida, a extensão não é carregada, mas o Chrome dá uma dica de como corrigir o problema.

Desfaça essa alteração e insira uma permissão inválida para ver o que acontece. Mude a permissão de "activeTab" para letras minúsculas com "activetab":

manifest.json:

{
  ...
  "permissions": ["activeTab", "scripting", "storage"],
  "permissions": ["activetab", "scripting", "storage"],
  ...
}

Salve a extensão e tente carregá-la novamente. Ele será carregado dessa vez. Na extensão de gerenciamento, você verá três botões: Detalhes, Remover e Erros. Os erros o rótulo do botão fica vermelho quando há um erro. Clique no botão Erros para ver as seguinte erro:

Permission 'activetab' is unknown or URL pattern is malformed.

Encontrar uma mensagem de erro clicando no botão "Erros".

Antes de continuar, mude a permissão novamente, clique em Clear all no canto superior direito para limpar os registros e recarregue a extensão.

Como limpar erros de extensão.

.

Observação:usar um esquema de manifesto no editor de código é uma maneira de garantir que o manifesto tenha a formatação correta e os campos obrigatórios.

Depurar o service worker

Localização de registros

O service worker define a cor padrão para o armazenamento e a registra no console. Para acessar esse registro, abra o painel do Chrome DevTools selecionando o link azul ao lado de Inspecionar visualizações.

Registros do service worker no painel do Chrome DevTools.

.

Ponto-chave: inspecionar o service worker o mantém ativo. Para garantir que a extensão se comporte corretamente quando o service worker for encerrado, feche o DevTools.

Erros de localização

Vamos interromper o service worker mudando onInstalled para oninstalled em letras minúsculas:

service-worker.js:

// There's a typo in the line below;
// ❌ oninstalled should be ✅ onInstalled.
chrome.runtime.onInstalled.addListener(() => { 
chrome.runtime.oninstalled.addListener(() => { 
  chrome.storage.sync.set({ color: '#3aa757' }, () => {
    console.log('The background color is green.');
  });
});

Atualize e clique em Erros para visualizar o registro de erros. O primeiro erro informa que o service worker não foi registrado. Isso significa que algo deu errado durante o início:

Service worker registration failed. Status code: 15.

Mensagem de erro de registro do service worker.

.

Observação:se o service worker falhar no registro, não será possível acessar o Chrome DevTools até corrigir o bug no registro.

O erro real ocorre depois de:

Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')

Mensagem TypeError não capturada.

Desfaça o bug que apresentamos, clique em Clear all no canto superior direito e recarregue a extensão.

Verificar o status do service worker

É possível identificar quando o service worker é ativado para executar tarefas seguindo estas etapas:

1. Copie o ID da extensão localizado acima de "Inspecionar visualizações".

   

   ID da extensão na página "Gerenciamento de extensões".

2. Abra o arquivo de manifesto no navegador. Exemplo: text chrome-extension://YOUR_EXTENSION_ID/manifest.json
3. Inspecione o arquivo.
4. Navegue até o painel Aplicativo.
5. Acesse o painel Service Workers.

Para testar seu código, inicie ou interrompa o service worker usando os links ao lado de status.

Status do service worker no painel "Application". (Clique para ampliar a imagem.)

Além disso, se tiver feito alterações no código do service worker, clique em Update ou skipWaiting para aplicar as alterações imediatamente.

Atualização do service worker no painel Application. (Clique para ampliar a imagem.)

.

Observação:isso não recarregará nenhum outro componente da extensão.

Depurar o pop-up

Agora que a extensão é inicializada corretamente, vamos quebrar o pop-up comentando as linhas destacadas abaixo:

popup.js:

...
changeColorButton.addEventListener('click', (event) => {
  const color = event.target.value;

  // Query the active tab before injecting the content script
  chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => { 
    // Use the Scripting API to execute a script
    chrome.scripting.executeScript({
      target: { tabId: tabs[0].id },
      args: [color],
      func: setColor
    });
  });
});

Volte para a página "Gerenciamento de extensões". O botão Erros será reexibido. Clique nele para visualizar o novo registro. Ela mostra a seguinte mensagem de erro:

Uncaught ReferenceError: tabs is not defined

Página de gerenciamento de extensões exibindo um erro de pop-up.

Inspecione o pop-up para abrir as DevTools do pop-up.

DevTools mostrando um erro de pop-up.

O erro tabs is undefined diz que a extensão não sabe onde injetar o script de conteúdo. Para corrigir isso, chame tabs.query() e selecione a guia ativa.

Para atualizar o código, clique no botão Limpar tudo no canto superior direito e recarregue o .

Observação:para outras páginas de extensão exibidas como uma guia, como páginas de substituição e opções de página inteira, é possível encontrar os registros inspecionando a página ou acessando a página “Gerenciamento de extensões”.

Depurar scripts de conteúdo

Agora, vamos quebrar o script de conteúdo alterando a variável "color" para "colors":

content.js:

...
function setColor(color) {
  // There's a typo in the line below;
  // ❌ colors should be ✅ color.
  document.body.style.backgroundColor = color;
  document.body.style.backgroundColor = colors;
}  

Atualize a página, abra o pop-up e clique na caixa verde. Nada acontece.

Se você acessar a página "Gerenciamento de extensões", o botão Erros não será exibido. Isso ocorre porque apenas os erros de execução, console.warning e console.error são registrados na página "Gerenciamento de extensões".

Scripts de conteúdo são executados dentro de um site. Portanto, para encontrar esses erros, precisamos inspecionar a página da Web que a extensão está tentando alterar:

Uncaught ReferenceError: colors is not defined

Erro de extensão exibido no console da página da Web.

Para usar o DevTools no script de conteúdo, clique na seta suspensa ao lado de top e selecione a extensão.

Referência não capturada: as cores não foram definidas.

O erro diz que colors não está definido. A extensão não pode transmitir a variável corretamente. Corrija o script injetado para transmitir a variável de cor ao código.

Monitorar solicitações de rede

O pop-up muitas vezes faz todas as solicitações de rede necessárias antes mesmo da desenvolvedores podem abrir o DevTools. Para ver essas solicitações, atualize no painel “Network”. Ela recarrega o pop-up sem fechar o painel DevTools.

Atualize o painel “Network” para ver as solicitações de rede em pop-up.

Declarar permissões

Algumas APIs de extensão exigem permissões. Consulte o artigo de permissões e os recursos do Google Chrome APIs para garantir que uma extensão esteja solicitando as permissões corretas no manifesto.

  {
    "name": "Broken Background Color",
    ...
    "permissions": [
      "activeTab",
      "declarativeContent",
      "storage"
    ],
  ...
  }

Importante:para fazer chamadas fetch() para um servidor externo, declare o URL como uma permissão de host.

Leitura adicional

Leia a documentação para saber mais sobre as Chrome Devtools.