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.

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.

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.

.

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.

.

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.

.

O erro real ocorre depois de:

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

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

   

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.

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.

.

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

Inspecione o pop-up para abrir as DevTools do 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 .

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

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

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.

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"
    ],
  ...
  }

Leitura adicional

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