Depurador

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

O Node.js inclui um utilitário de depuração de linha de comando. O cliente de depurador do Node.js não é um depurador completo, mas é possível executar passos e inspeções simples.

Para usá-lo, inicie o Node.js com o argumento inspect seguido pelo caminho para o script a ser depurado.

$ node inspect myscript.js
< Depurador escutando em ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
< Para ajuda, consulte: https://nodejs.org/en/docs/inspector
<
conectando a 127.0.0.1:9229 ... ok
< Depurador anexado.
<
 ok
Parar no início em myscript.js:2
  1 // myscript.js
> 2 global.x = 5;
  3 setTimeout(() => {
  4   debugger;
debug>

O depurador para automaticamente na primeira linha executável. Para, em vez disso, executar até o primeiro ponto de interrupção (especificado por uma declaração debugger), defina a variável de ambiente NODE_INSPECT_RESUME_ON_START como 1.

$ cat myscript.js
// myscript.js
global.x = 5;
setTimeout(() => {
  debugger;
  console.log('world');
}, 1000);
console.log('hello');
$ NODE_INSPECT_RESUME_ON_START=1 node inspect myscript.js
< Depurador escutando em ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2
< Para ajuda, consulte: https://nodejs.org/en/docs/inspector
<
conectando a 127.0.0.1:9229 ... ok
< Depurador anexado.
<
< hello
<
parar em myscript.js:4
  2 global.x = 5;
  3 setTimeout(() => {
> 4   debugger;
  5   console.log('world');
  6 }, 1000);
debug> next
parar em myscript.js:5
  3 setTimeout(() => {
  4   debugger;
> 5   console.log('world');
  6 }, 1000);
  7 console.log('hello');
debug> repl
Pressione Ctrl+C para sair do repl de depuração
> x
5
> 2 + 2
4
debug> next
< world
<
parar em myscript.js:6
  4   debugger;
  5   console.log('world');
> 6 }, 1000);
  7 console.log('hello');
  8
debug> .exit
$

O comando repl permite que o código seja avaliado remotamente. O comando next avança para a próxima linha. Digite help para ver quais outros comandos estão disponíveis.

Pressionar enter sem digitar um comando repetirá o comando de depuração anterior.

Observadores

É possível observar expressões e valores de variáveis durante a depuração. Em cada ponto de interrupção, cada expressão da lista de observadores será avaliada no contexto atual e exibida imediatamente antes da listagem do código-fonte do ponto de interrupção.

Para começar a observar uma expressão, digite watch('minha_expressao'). O comando watchers imprimirá os observadores ativos. Para remover um observador, digite unwatch('minha_expressao').

Referência de comandos

Passos

• cont, c: Continuar a execução
• next, n: Próximo passo
• step, s: Entrar em
• out, o: Sair de
• pause: Pausar o código em execução (como o botão de pausa nas Ferramentas de Desenvolvedor)

Pontos de interrupção

• setBreakpoint(), sb(): Definir ponto de interrupção na linha atual
• setBreakpoint(linha), sb(linha): Definir ponto de interrupção em uma linha específica
• setBreakpoint('fn()'), sb(...): Definir ponto de interrupção na primeira instrução do corpo da função
• setBreakpoint('script.js', 1), sb(...): Definir ponto de interrupção na primeira linha de script.js
• setBreakpoint('script.js', 1, 'num \< 4'), sb(...): Definir ponto de interrupção condicional na primeira linha de script.js que só interrompe quando num \< 4 avalia para true
• clearBreakpoint('script.js', 1), cb(...): Limpar o ponto de interrupção em script.js na linha 1

Também é possível definir um ponto de interrupção em um arquivo (módulo) que ainda não foi carregado:

$ node inspect main.js
< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
< For help, see: https://nodejs.org/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
<
Break on start in main.js:1
> 1 const mod = require('./mod.js');
  2 mod.hello();
  3 mod.hello();
debug> setBreakpoint('mod.js', 22)
Warning: script 'mod.js' was not loaded yet.
debug> c
break in mod.js:22
 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 21
>22 exports.hello = function() {
 23   return 'hello from module';
 24 };
debug>

Também é possível definir um ponto de interrupção condicional que só interrompe quando uma dada expressão avalia para true:

$ node inspect main.js
< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
< For help, see: https://nodejs.org/en/docs/inspector
<
connecting to 127.0.0.1:9229 ... ok
< Debugger attached.
Break on start in main.js:7
  5 }
  6
> 7 addOne(10);
  8 addOne(-1);
  9
debug> setBreakpoint('main.js', 4, 'num < 0')
  1 'use strict';
  2
  3 function addOne(num) {
> 4   return num + 1;
  5 }
  6
  7 addOne(10);
  8 addOne(-1);
  9
debug> cont
break in main.js:4
  2
  3 function addOne(num) {
> 4   return num + 1;
  5 }
  6
debug> exec('num')
-1
debug>

Informação

• backtrace, bt: Imprime o rastreamento da pilha do quadro de execução atual
• list(5): Lista o código-fonte do script com 5 linhas de contexto (5 linhas antes e depois)
• watch(expr): Adiciona expressão à lista de observação
• unwatch(expr): Remove expressão da lista de observação
• unwatch(index): Remove expressão em um índice específico da lista de observação
• watchers: Lista todos os observadores e seus valores (listados automaticamente em cada ponto de interrupção)
• repl: Abre o repl do depurador para avaliação no contexto do script de depuração
• exec expr, p expr: Executa uma expressão no contexto do script de depuração e imprime seu valor
• profile: Inicia uma sessão de criação de perfil da CPU
• profileEnd: Interrompe a sessão atual de criação de perfil da CPU
• profiles: Lista todas as sessões de criação de perfil da CPU concluídas
• profiles[n].save(filepath = 'node.cpuprofile'): Salva a sessão de criação de perfil da CPU em disco como JSON
• takeHeapSnapshot(filepath = 'node.heapsnapshot'): Tira um instantâneo do heap e salva em disco como JSON

Controle de execução

• run: Executa o script (executa automaticamente na inicialização do depurador)
• restart: Reinicia o script
• kill: Mata o script

Vários

• scripts: Lista todos os scripts carregados
• version: Exibe a versão do V8

Uso avançado

Integração do inspetor V8 para Node.js

A integração do Inspetor V8 permite anexar o Chrome DevTools a instâncias do Node.js para depuração e criação de perfil. Ele usa o Chrome DevTools Protocol.

O Inspetor V8 pode ser habilitado passando a flag --inspect ao iniciar um aplicativo Node.js. Também é possível fornecer uma porta personalizada com essa flag, por exemplo, --inspect=9222 aceitará conexões do DevTools na porta 9222.

Usar a flag --inspect executará o código imediatamente antes que o depurador seja conectado. Isso significa que o código começará a ser executado antes que você possa começar a depurar, o que pode não ser ideal se você quiser depurar desde o início.

Nesses casos, você tem duas alternativas:

Portanto, ao decidir entre --inspect, --inspect-wait e --inspect-brk, considere se deseja que o código comece a ser executado imediatamente, aguarde a conexão do depurador antes da execução ou pare na primeira linha para depuração passo a passo.

$ node --inspect index.js
Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
For help, see: https://nodejs.org/en/docs/inspector

(No exemplo acima, o UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29 no final do URL é gerado dinamicamente, ele varia em diferentes sessões de depuração.)

Se o navegador Chrome for mais antigo que 66.0.3345.0, use inspector.html em vez de js_app.html no URL acima.

O Chrome DevTools ainda não suporta a depuração de threads de trabalho. O ndb pode ser usado para depurá-los.