W3docs
pt
Entrar

Depuração e Ferramentas no Desenvolvimento Web

Aprenda a depurar JavaScript que manipula o DOM usando as ferramentas do navegador: inspecione elementos, use o console, defina breakpoints e corrija problemas comuns no DOM.

Quando um script que trabalha com o DOM se comporta de forma inesperada, a maneira mais rápida de descobrir o porquê é observar a página do ponto de vista do navegador. As ferramentas de desenvolvimento do navegador (DevTools) permitem que você leia a árvore do DOM em tempo real, pause a execução do JavaScript no meio do caminho e veja exatamente o que cada linha faz na página.

Este guia aborda quatro habilidades práticas: abrir e usar as DevTools, inspecionar elementos, registrar e percorrer o código DOM passo a passo, e corrigir os poucos bugs que são responsáveis pela maioria dos problemas com o DOM.

Usando as Ferramentas de Desenvolvimento do Navegador

Inspecionando o DOM

As ferramentas de desenvolvimento do navegador são utilitários integrados aos navegadores modernos para inspecionar e editar o DOM ao vivo, depurar JavaScript, monitorar requisições de rede e medir desempenho. Os painéis mais úteis para trabalhar com o DOM são:

  • Elements (Firefox: Inspector) — a árvore do DOM ao vivo e o CSS aplicado a cada nó.
  • Console — logs, erros e um REPL onde você pode executar JavaScript na página atual.
  • Sources (Firefox: Debugger) — seus scripts, onde você define breakpoints e percorre o código passo a passo.

Um ponto importante que confunde iniciantes: o painel Elements mostra o DOM ao vivo, não o HTML que você escreveu. Se o seu script adiciona, remove ou reescreve nós, o painel Elements reflete o resultado após a execução do script — que é exatamente o que você quer ao depurar a manipulação do DOM.

Como Abrir as Ferramentas de Desenvolvimento

  • Chrome: Clique com o botão direito na página e selecione "Inspecionar", ou pressione Ctrl+Shift+I (Windows/Linux) ou Cmd+Opt+I (Mac).
  • Firefox: Clique com o botão direito na página e selecione "Inspecionar Elemento", ou pressione Ctrl+Shift+I (Windows/Linux) ou Cmd+Opt+I (Mac).
  • Safari: Ative o menu Desenvolver nas Preferências, depois selecione "Mostrar Inspetor Web" no menu Desenvolver.

Inspecionando Elementos

O painel "Elements" permite inspecionar e editar o HTML e o CSS de uma página web em tempo real.

<!DOCTYPE html>
<html>
<head>
    <title>Inspecting Elements</title>
    <style>
        .highlight {
            color: red;
        }
    </style>
</head>
<body>
    <div class="content">This is some content.</div>
    <script>
        document.querySelector('.content').classList.add('highlight');
    </script>
</body>
</html>
Experimente Você Mesmo »

Use o painel Elements (pressione F12 para abrir o Inspector e navegue até a aba Elements) para inspecionar o elemento <div class="content"> e verificar se a classe .highlight foi aplicada.

Depurando JavaScript que Manipula o DOM

Usando o Console

O console é a ferramenta de depuração mais rápida: insira uma instrução de log, recarregue e leia a saída. Além do básico console.log(), vários métodos tornam a depuração do DOM muito mais clara:

  • console.log() — saída geral; passe vários argumentos e eles serão exibidos lado a lado.
  • console.error() / console.warn() — mensagens estilizadas em vermelho/amarelo, fáceis de identificar e filtrar.
  • console.dir(node) — exibe um nó do DOM como um objeto JavaScript para que você possa expandir suas propriedades, em vez de como HTML (que é o que console.log(node) mostra).
  • console.table(data) — renderiza arrays e objetos como uma tabela ordenável.
  • console.assert(condition, msg) — registra apenas quando a condição é false, ideal para verificações de sanidade.
  • console.count(label) — conta quantas vezes uma linha é executada, útil para detectar um handler de evento que dispara com frequência excessiva.
const items = [
  { id: 1, name: 'Alpha' },
  { id: 2, name: 'Beta' },
];

console.log('Loaded items:', items.length); // Loaded items: 2
console.table(items);                        // sortable table of both rows
console.assert(items.length > 0, 'No items!'); // silent: condition is true
console.assert(items.length > 5, 'Too few items'); // logs the assertion message

Ao registrar um nó do DOM, prefira console.dir(el) para inspecionar suas propriedades (como el.dataset ou el.classList) e console.log(el) para inspecionar seu HTML renderizado — eles mostram duas visões diferentes do mesmo elemento.

Definindo Breakpoints

Os breakpoints permitem pausar a execução do JavaScript em linhas específicas do código para inspecionar variáveis e a pilha de chamadas.

Como Definir Breakpoints

  1. Abra o painel "Sources" no Chrome ou o painel "Debugger" no Firefox.
  2. Navegue até o arquivo JavaScript que deseja depurar.
  3. Clique no número da linha onde deseja definir um breakpoint.

Quando a execução pausar, use os controles de avanço: Step over (executa a linha atual), Step into (entra em uma função chamada) e Step out (finaliza a função atual). O painel Scope mostra as variáveis locais, e Call Stack mostra como você chegou a essa linha.

A instrução debugger

Você também pode pausar a partir do próprio código. Quando as DevTools estão abertas, a instrução debugger; age como um breakpoint que fica no seu código-fonte — prático para código gerado em tempo de execução ou que você não consegue clicar facilmente no painel Sources:

function updateTitle(text) {
  debugger; // execution pauses here when DevTools is open
  document.title = text;
}

Se as DevTools estiverem fechadas, debugger não faz nada, então é seguro mantê-lo durante o desenvolvimento (mas remova-o antes de publicar).

Breakpoints condicionais e logpoints

Para um handler que executa muitas vezes, clique com o botão direito em um número de linha e escolha Add conditional breakpoint para pausar apenas quando uma expressão for verdadeira (por exemplo, count > 100). Um logpoint exibe uma mensagem sem pausar — como um console.log() que você pode adicionar sem editar o código-fonte.

Exemplo de Depuração de Manipulação do DOM

<!DOCTYPE html>
<html>
<head>
    <title>Debugging Example</title>
</head>
<body>
    <div id="content">Hello, World!</div>
    <button id="change-text">Change Text</button>
    <p id="log"></p>

    <script>
        document.getElementById('change-text').addEventListener('click', function() {
            const content = document.getElementById('content');
            const log = document.getElementById('log');
            log.textContent = 'Current text: ' + content.textContent;
            content.textContent = 'Hello, Developer!';
            log.textContent += ' | Updated text: ' + content.textContent;
        });
    </script>
</body>
</html>
Experimente Você Mesmo »

Este exemplo demonstra como depurar a manipulação do DOM exibindo as alterações no DOM.

Problemas Comuns e Soluções

Solucionando Problemas Comuns de Manipulação do DOM

  1. Elemento Não Encontrado

    O erro de DOM mais comum é TypeError: Cannot read properties of null. Isso significa que um seletor retornou null porque o elemento não existe (um erro de digitação no id ou o seletor errado). Sempre verifique o resultado antes de usá-lo. Consulte Pesquisa: getElement, querySelector para entender a diferença entre os métodos de seletor.

const element = document.getElementById('nonexistent');
if (element) {
    element.textContent = 'Found!';
} else {
    document.body.insertAdjacentHTML('beforeend', '<p>Element not found</p>');
}

  1. Timing Incorreto

    Se um <script> no <head> for executado antes que o body seja analisado, os elementos que ele procura ainda não existem — produzindo o mesmo erro null descrito acima. Execute o código do DOM após o documento ser analisado ouvindo o evento DOMContentLoaded (ou colocando o script no final do <body>).

document.addEventListener('DOMContentLoaded', function() {
    const element = document.getElementById('content');
    element.textContent = 'DOM fully loaded';
});

  1. CSS Não Aplicado

    Se uma alteração de estilo não produz efeito visível, confirme no painel Elements que a classe foi realmente adicionada (element.classList) e que nenhuma regra mais específica a sobrescreve — as DevTools mostram regras substituídas com um riscado. Relacionado: Tratamento de eventos no DOM.

<!DOCTYPE html>
<html>
<head>
    <title>CSS Not Applied</title>
    <style>
        .hidden {
            display: none;
        }
    </style>
</head>
<body>
    <div id="content">This is visible</div>
    <button id="hide-content">Hide Content</button>

    <script>
        document.getElementById('hide-content').addEventListener('click', function() {
            const content = document.getElementById('content');
            content.classList.add('hidden');
        });
    </script>
</body>
</html>
Experimente Você Mesmo »

Este exemplo demonstra como ocultar um elemento de conteúdo adicionando a classe .hidden.

Informação

Use o painel "Sources" nas ferramentas de desenvolvimento do navegador para definir breakpoints e percorrer seu código JavaScript linha a linha. Isso permite inspecionar variáveis, a pilha de chamadas e o estado do DOM em cada etapa, tornando muito mais fácil identificar e corrigir bugs.

Conclusão

As ferramentas de desenvolvimento do navegador são indispensáveis para inspecionar o DOM, depurar JavaScript e solucionar problemas comuns. Ao dominar essas ferramentas e técnicas, você pode melhorar significativamente seu fluxo de trabalho de desenvolvimento e criar aplicações web mais confiáveis.

Prática

Prática
Quais das afirmações a seguir sobre depuração e ferramentas para manipulação do DOM são verdadeiras?
Quais das afirmações a seguir sobre depuração e ferramentas para manipulação do DOM são verdadeiras?
Was this page helpful?