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.
![Uma extensão com uma chave de manifesto inválida que aciona uma caixa de diálogo de erro ao tentar carregar.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/an-extension-an-invalid-9ab91f867f94c.png?authuser=6&hl=pt)
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.
![O botão "Error" é clicado e exibe um erro](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/error-button-is-clicked-a7713a11553a.gif?authuser=6&hl=pt)
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.
![Botão "Limpar tudo"](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/clear-button-2f67dd9230519.png?authuser=6&hl=pt)
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.
![Como abrir o DevTools para o service worker de extensão.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/opening-devtools-the-ex-685e204e20773.png?authuser=6&hl=pt)
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.
![Falha no registro do service worker. Código de status: mensagem de erro 15](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/service-worker-registrati-9791df79120e6.png?authuser=6&hl=pt)
O erro real vem depois:
Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
![TypeError não capturado: não é possível ler as propriedades da mensagem de erro indefinida](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/uncaught-typeerror-canno-45ae014961338.png?authuser=6&hl=pt)
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:
- Copie o ID da extensão localizado acima de "Inspecionar visualizações".
ID da extensão na página "Gerenciamento de extensões". - Abra o arquivo de manifesto no navegador. Exemplo:
text chrome-extension://YOUR_EXTENSION_ID/manifest.json
- Inspecione o arquivo.
- Navegue até o painel Aplicativo.
- Acesse o painel Service Workers.
Para testar o código, inicie ou pare o service worker usando os links ao lado de status.
![Status do service worker no painel "Aplicativo"](https://developer.chrome.com/docs/extensions/get-started/tutorial/debug/image/start-stop-service-worker.png?auto=format&w=845&authuser=6&hl=pt)
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.
![Status do service worker no painel "Aplicativo"](https://developer.chrome.com/docs/extensions/get-started/tutorial/debug/image/update-or-skipwaiting.png?auto=format&w=845&authuser=6&hl=pt)
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
![Página de gerenciamento de extensões exibindo erro pop-up](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/extensions-management-pag-00a0f48a76239.png?authuser=6&hl=pt)
Inspecione o pop-up para abrir o DevTools do pop-up.
![O DevTools exibe um erro pop-up.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/devtools-displaying-popup-0ed24fd80361a.png?authuser=6&hl=pt)
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
![Erro de extensão exibido no console da página da Web](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/extension-error-displayed-ca9d8c6c336b.png?authuser=6&hl=pt)
Para usar o DevTools no script de conteúdo, clique na seta suspensa ao lado de top e selecione a extensão.
![ReferenceError não capturado: as cores não estão definidas](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/uncaught-referenceerror-e5847be3a7de9.png?authuser=6&hl=pt)
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.
![Atualize dentro do painel de rede para ver as solicitações pop-up de rede](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/refresh-inside-network-p-43993068e650e.gif?authuser=6&hl=pt)
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.