JavaScript console API
A Console API é uma ferramenta essencial para desenvolvedores web, permitindo interagir com o console do navegador para depuração e logging em JavaScript.
Introdução à Console API
A Console API é o conjunto de métodos console.* que permitem ao seu JavaScript se comunicar com o console do desenvolvedor — o painel que você abre com o DevTools do navegador (Chrome, Firefox, Edge, Safari) ou que o Node.js imprime no seu terminal. É a ferramenta de depuração mais usada em JavaScript: com uma única linha você pode inspecionar um valor, medir o tempo de uma operação ou imprimir um rastreamento de pilha, sem alterar o comportamento do seu programa.
Esta página cobre os métodos que você usará todos os dias — log, info, warn, error, table, dir, group, time, count, assert e trace — além dos especificadores de formato (%s, %d, %c) que controlam como os valores são impressos.
O console está disponível globalmente, portanto você pode chamar esses métodos em qualquer lugar — em um script de navegador, no console do DevTools ou em um arquivo Node.js.
Logging básico com console.log()
console.log() imprime informações no console. Aceita qualquer número de argumentos de qualquer tipo e os separa com espaços — strings, números, arrays e objects são todos formatados automaticamente.
Registrar um rótulo ao lado de um valor ('Value of y:', y) é a técnica de depuração mais simples e comum — mantém a saída legível quando vários logs passam na tela.
Níveis de log: info, warn e error
console.info(), console.warn() e console.error() funcionam exatamente como console.log(), mas carregam um nível de severidade. O navegador estiliza cada um de forma diferente (avisos recebem fundo amarelo, erros recebem fundo vermelho) e — importante — o DevTools permite filtrar por nível, para que você possa ocultar o ruído e exibir apenas erros quando uma página apresentar problemas.
Use console.warn() para situações recuperáveis mas que merecem atenção (uma opção depreciada, um campo opcional ausente) e console.error() para falhas genuínas. Combine console.error() com o tratamento de erros com try...catch adequado para que as falhas sejam tanto relatadas quanto tratadas.
Formatando a saída com especificadores de formato
Quando o primeiro argumento de um método console contém um especificador de formato, os argumentos restantes são substituídos no lugar. Os especificadores mais comuns são:
%s— uma string%d(ou%i) — um inteiro%f— um número de ponto flutuante%o/%O— um object%c— aplica estilo CSS à saída (somente no navegador)
No Node.js, o estilo %c é ignorado, mas o texto ainda é impresso. Os especificadores de formato são úteis quando você quer uma saída limpa, semelhante a frases, em vez de valores separados por vírgula.
Exibindo dados estruturados
Tabelas com console.table()
console.table() renderiza um array de objects (ou um object de objects) como uma tabela ordenável — muito mais fácil de examinar do que a saída aninhada de console.log().
Inspecionando objects com console.dir()
console.dir() imprime uma listagem interativa e navegável das propriedades de um object. É especialmente útil para nós do DOM: console.log(element) mostra o HTML renderizado, enquanto console.dir(element) mostra o elemento como um object JavaScript com todas as suas propriedades.
Organizando e contando logs
Agrupamento com console.group()
console.group() e console.groupEnd() recuam e (no navegador) recolhem os logs entre eles — perfeito para agrupar saídas relacionadas durante uma sessão de depuração complexa.
Use console.groupCollapsed() em vez de console.group() para iniciar o grupo já recolhido por padrão.
Contagem com console.count()
console.count(label) imprime quantas vezes foi chamado com aquele rótulo — uma forma rápida de ver com que frequência uma função é executada ou um trecho de código é ativado, sem precisar manter uma variável contadora.
Asserções e rastreamentos de pilha
Asserções com console.assert()
console.assert(condition, message) registra a mensagem somente quando a condição é falsa. Quando a condição é verdadeira, não produz saída alguma, então você pode deixar verificações de sanidade no lugar sem poluir o console.
Rastreamentos de pilha com console.trace()
console.trace() imprime a pilha de chamadas atual — a cadeia de chamadas de função que levou a este ponto. É a maneira mais rápida de responder à pergunta "como a execução chegou aqui?"
Medindo desempenho
console.time(label) inicia um temporizador e console.timeEnd(label) o para e imprime os milissegundos decorridos. Use o mesmo rótulo em ambas as chamadas. Esta é uma alternativa leve ao performance.now() para identificar operações lentas.
Próximos passos
A Console API é uma parte de um conjunto mais amplo de ferramentas de depuração. Para breakpoints, o painel Sources e o restante do DevTools, consulte Depuração do DOM e ferramentas. E embora as chamadas ao console sejam ótimas durante o desenvolvimento, prefira comentários de código descritivos para explicações que devem permanecer permanentemente no código-fonte — e lembre-se de remover chamadas console.log perdidas antes de publicar.
Conclusão
A Console API oferece uma maneira rápida e sem configuração de entender o que seu código está fazendo: log/info/warn/error para mensagens com níveis, table e dir para dados estruturados, group e count para organizar a saída, time para desempenho e assert/trace para capturar e explicar bugs. Combinados com especificadores de formato, esses métodos cobrem a grande maioria das necessidades de depuração diária em JavaScript.