Debugger

[Stable: 2 - Stable]

Stable: 2 Stabilità: 2 - Stabile

Node.js include un'utilità di debug da riga di comando. Il client di debug di Node.js non è un debugger completo, ma è possibile eseguire semplici passaggi e ispezioni.

Per utilizzarlo, avvia Node.js con l'argomento inspect seguito dal percorso dello script da sottoporre a debug.

$ node inspect myscript.js
< Debugger in ascolto su ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
< Per aiuto, consulta: https://nodejs.org/en/docs/inspector
<
connessione a 127.0.0.1:9229 ... ok
< Debugger collegato.
<
 ok
Interruzione all'avvio in myscript.js:2
  1 // myscript.js
> 2 global.x = 5;
  3 setTimeout(() => {
  4   debugger;
debug>

Il debugger si interrompe automaticamente alla prima riga eseguibile. Per invece eseguire fino al primo breakpoint (specificato da un'istruzione debugger), imposta la variabile d'ambiente NODE_INSPECT_RESUME_ON_START su 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
< Debugger in ascolto su ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2
< Per aiuto, consulta: https://nodejs.org/en/docs/inspector
<
connessione a 127.0.0.1:9229 ... ok
< Debugger collegato.
<
< hello
<
interruzione in myscript.js:4
  2 global.x = 5;
  3 setTimeout(() => {
> 4   debugger;
  5   console.log('world');
  6 }, 1000);
debug> next
interruzione in myscript.js:5
  3 setTimeout(() => {
  4   debugger;
> 5   console.log('world');
  6 }, 1000);
  7 console.log('hello');
debug> repl
Premi Ctrl+C per uscire da debug repl
> x
5
> 2 + 2
4
debug> next
< world
<
interruzione in myscript.js:6
  4   debugger;
  5   console.log('world');
> 6 }, 1000);
  7 console.log('hello');
  8
debug> .exit
$

Il comando repl consente di valutare il codice in remoto. Il comando next passa alla riga successiva. Digita help per vedere quali altri comandi sono disponibili.

Premere invio senza digitare un comando ripeterà il comando del debugger precedente.

Osservatori

È possibile osservare le espressioni e i valori delle variabili durante il debug. Ad ogni breakpoint, ogni espressione dalla lista degli osservatori verrà valutata nel contesto corrente e visualizzata immediatamente prima dell'elenco del codice sorgente del breakpoint.

Per iniziare a osservare un'espressione, digita watch('mia_espressione'). Il comando watchers stamperà gli osservatori attivi. Per rimuovere un osservatore, digita unwatch('mia_espressione').

Riferimento dei comandi

Esecuzione passo passo

• cont, c: Continua l'esecuzione
• next, n: Passo successivo
• step, s: Entra nel passo
• out, o: Esci dal passo
• pause: Metti in pausa il codice in esecuzione (come il pulsante di pausa negli Strumenti per sviluppatori)

Breakpoint

• setBreakpoint(), sb(): Imposta un breakpoint sulla linea corrente
• setBreakpoint(line), sb(line): Imposta un breakpoint su una linea specifica
• setBreakpoint('fn()'), sb(...): Imposta un breakpoint sulla prima istruzione nel corpo della funzione
• setBreakpoint('script.js', 1), sb(...): Imposta un breakpoint sulla prima linea di script.js
• setBreakpoint('script.js', 1, 'num < 4'), sb(...): Imposta un breakpoint condizionale sulla prima linea di script.js che si interrompe solo quando num < 4 restituisce true
• clearBreakpoint('script.js', 1), cb(...): Cancella il breakpoint in script.js sulla linea 1

È anche possibile impostare un breakpoint in un file (modulo) che non è ancora stato caricato:

$ 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>

È anche possibile impostare un breakpoint condizionale che si interrompe solo quando una data espressione restituisce 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>

Informazioni

• backtrace, bt: Stampa il backtrace del frame di esecuzione corrente
• list(5): Elenca il codice sorgente dello script con un contesto di 5 linee (5 linee prima e dopo)
• watch(expr): Aggiungi un'espressione alla lista di osservazione
• unwatch(expr): Rimuovi un'espressione dalla lista di osservazione
• unwatch(index): Rimuovi un'espressione ad un indice specifico dalla lista di osservazione
• watchers: Elenca tutti gli osservatori e i loro valori (elencati automaticamente ad ogni breakpoint)
• repl: Apri la repl del debugger per la valutazione nel contesto dello script di debug
• exec expr, p expr: Esegui un'espressione nel contesto dello script di debug e stampa il suo valore
• profile: Avvia una sessione di profilazione CPU
• profileEnd: Interrompi la sessione di profilazione CPU corrente
• profiles: Elenca tutte le sessioni di profilazione CPU completate
• profiles[n].save(filepath = 'node.cpuprofile'): Salva la sessione di profilazione CPU su disco come JSON
• takeHeapSnapshot(filepath = 'node.heapsnapshot'): Acquisisci uno snapshot dell'heap e salvalo su disco come JSON

Controllo dell'esecuzione

• run: Esegui lo script (esegue automaticamente all'avvio del debugger)
• restart: Riavvia lo script
• kill: Interrompi lo script

Varie

• scripts: Elenca tutti gli script caricati
• version: Visualizza la versione di V8

Utilizzo avanzato

Integrazione di V8 inspector per Node.js

L'integrazione di V8 Inspector permette di collegare Chrome DevTools alle istanze di Node.js per il debug e la profilazione. Utilizza il Chrome DevTools Protocol.

V8 Inspector può essere abilitato passando il flag --inspect all'avvio di un'applicazione Node.js. È anche possibile fornire una porta personalizzata con quel flag, ad esempio --inspect=9222 accetterà le connessioni di DevTools sulla porta 9222.

L'utilizzo del flag --inspect eseguirà il codice immediatamente prima che il debugger sia connesso. Ciò significa che il codice inizierà a essere eseguito prima di poter iniziare il debug, il che potrebbe non essere l'ideale se si desidera eseguire il debug fin dall'inizio.

In tali casi, hai due alternative:

Quindi, quando si decide tra --inspect, --inspect-wait e --inspect-brk, considera se si desidera che il codice inizi a essere eseguito immediatamente, attenda che il debugger sia collegato prima dell'esecuzione o si interrompa sulla prima riga per il debug passo-passo.

$ node --inspect index.js
Debugger in ascolto su ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
Per assistenza, vedi: https://nodejs.org/en/docs/inspector

(Nell'esempio sopra, l'UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29 alla fine dell'URL viene generato al volo, varia in diverse sessioni di debug.)

Se il browser Chrome è precedente alla versione 66.0.3345.0, utilizzare inspector.html invece di js_app.html nell'URL sopra.

Chrome DevTools non supporta ancora il debug dei thread worker. ndb può essere utilizzato per eseguirne il debug.