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 de extensão. Neste tutorial, fornecemos 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 da Web. Recomendamos a leitura de Princípios básicos de desenvolvimento para uma introdução ao fluxo de trabalho de desenvolvimento de extensões. O artigo Projetar a interface do usuário apresenta uma introdução aos elementos da interface do usuário disponíveis nas extensões.

Interromper a extensão

Neste tutorial, vamos analisar 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 prosseguir para a próxima. Para começar, faça o download do exemplo de cor quebrada (link em inglês) no GitHub.

Depurar o manifesto

Primeiro, vamos corromper o arquivo de manifesto alterando a chave "version" para "versions":

manifest.json:

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

Agora vamos tentar 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. Altere a permissão "activeTab" para "activetab" minúsculas:

manifest.json:

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

Salve a extensão e tente carregá-la novamente. Ele será carregado desta vez. Na página "Gerenciamento de extensões", você verá três botões: Detalhes, Remover e Erros. O rótulo do botão Errors fica em vermelho quando há um erro. Clique no botão Erros para ver o seguinte erro:

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

Antes de prosseguir, altere a permissão novamente, clique em Limpar tudo no canto superior direito para limpar os registros e atualize 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 conferir esse registro, abra o painel do Chrome DevTools selecionando o link azul ao lado de Inspecionar visualizações.

Localização de erros

Vamos interromper o service worker mudando onInstalled para oninstalled 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 vem depois:

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

Desfaça o bug introduzido, clique em Clear all no canto superior direito e atualize a extensão.

Verificar o status do service worker

Você pode identificar quando o service worker acorda 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 o código, inicie ou pare o service worker usando os links ao lado de status.

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

Depurar o pop-up

Agora que a extensão é inicializada corretamente, vamos interromper 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 reaparecerá. Clique nele para ver o novo registro. Ela mostra a seguinte mensagem de erro:

Uncaught ReferenceError: tabs is not defined

Inspecione o pop-up para abrir o 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 Clear all no canto superior direito e recarregue a extensão.

Depurar scripts de conteúdo

Agora, vamos interromper 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 aparecerá. Isso ocorre porque apenas erros de tempo 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 para o código.

Monitorar solicitações de rede

O pop-up geralmente faz todas as solicitações de rede necessárias antes mesmo que o desenvolvedor mais rápido possa abrir o DevTools. Para ver essas solicitações, atualize o painel "Network". Ele recarrega o pop-up sem fechar o painel do DevTools.

Declarar permissões

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

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

Leia mais

Saiba mais sobre as Chrome Devtools lendo a documentação.