Débogueur

[Stable: 2 - Stable]

Stable: 2 Stabilité : 2 - Stable

Node.js inclut un utilitaire de débogage en ligne de commande. Le client de débogage Node.js n’est pas un débogueur complet, mais le pas à pas et l’inspection simples sont possibles.

Pour l’utiliser, lancez Node.js avec l’argument inspect suivi du chemin vers le script à déboguer.

$ node inspect myscript.js
< Débogueur à l’écoute sur ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
< Pour de l’aide, consultez : https://nodejs.org/en/docs/inspector
<
connexion à 127.0.0.1:9229 ... ok
< Débogueur connecté.
<
 ok
Point d’arrêt au démarrage dans myscript.js:2
  1 // myscript.js
> 2 global.x = 5;
  3 setTimeout(() => {
  4   debugger;
debug>

Le débogueur s’arrête automatiquement à la première ligne exécutable. Pour exécuter plutôt jusqu’au premier point d’arrêt (spécifié par une instruction debugger), définissez la variable d’environnement NODE_INSPECT_RESUME_ON_START sur 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
< Débogueur à l’écoute sur ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2
< Pour de l’aide, consultez : https://nodejs.org/en/docs/inspector
<
connexion à 127.0.0.1:9229 ... ok
< Débogueur connecté.
<
< hello
<
point d’arrêt dans myscript.js:4
  2 global.x = 5;
  3 setTimeout(() => {
> 4   debugger;
  5   console.log('world');
  6 }, 1000);
debug> next
point d’arrêt dans myscript.js:5
  3 setTimeout(() => {
  4   debugger;
> 5   console.log('world');
  6 }, 1000);
  7 console.log('hello');
debug> repl
Appuyez sur Ctrl+C pour quitter le repl de débogage
> x
5
> 2 + 2
4
debug> next
< world
<
point d’arrêt dans myscript.js:6
  4   debugger;
  5   console.log('world');
> 6 }, 1000);
  7 console.log('hello');
  8
debug> .exit
$

La commande repl permet d’évaluer le code à distance. La commande next passe à la ligne suivante. Tapez help pour voir quelles autres commandes sont disponibles.

Appuyer sur Entrée sans taper de commande répétera la commande précédente du débogueur.

Observateurs

Il est possible de surveiller les valeurs des expressions et des variables pendant le débogage. À chaque point d'arrêt, chaque expression de la liste des observateurs sera évaluée dans le contexte actuel et affichée immédiatement avant la liste du code source du point d'arrêt.

Pour commencer à observer une expression, tapez watch('mon_expression'). La commande watchers affichera les observateurs actifs. Pour supprimer un observateur, tapez unwatch('mon_expression').

Référence des commandes

Déplacement pas à pas

• cont, c : Continuer l’exécution
• next, n : Aller à l’instruction suivante
• step, s : Entrer dans l’instruction
• out, o : Sortir de l’instruction
• pause : Mettre le code en pause (comme le bouton de pause dans les outils de développement)

Points d’arrêt

• setBreakpoint(), sb() : Définir un point d’arrêt sur la ligne actuelle
• setBreakpoint(ligne), sb(ligne) : Définir un point d’arrêt sur une ligne spécifique
• setBreakpoint('fn()'), sb(...) : Définir un point d’arrêt sur la première instruction du corps d’une fonction
• setBreakpoint('script.js', 1), sb(...) : Définir un point d’arrêt sur la première ligne de script.js
• setBreakpoint('script.js', 1, 'num < 4'), sb(...) : Définir un point d’arrêt conditionnel sur la première ligne de script.js qui ne s’interrompt que lorsque num < 4 est évalué à true
• clearBreakpoint('script.js', 1), cb(...) : Supprimer le point d’arrêt dans script.js à la ligne 1

Il est également possible de définir un point d’arrêt dans un fichier (module) qui n’est pas encore chargé :

$ node inspect main.js
< Débogueur à l'écoute sur ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
< Pour obtenir de l'aide, consultez : https://nodejs.org/en/docs/inspector
<
connexion à 127.0.0.1:9229... ok
< Débogueur attaché.
<
Point d'arrêt au démarrage dans main.js:1
> 1 const mod = require('./mod.js');
  2 mod.hello();
  3 mod.hello();
debug> setBreakpoint('mod.js', 22)
Avertissement : le script « mod.js » n'a pas encore été chargé.
debug> c
Point d'arrêt dans mod.js:22
 20 // USAGE OU AUTRES TRANSACTIONS DANS LE LOGICIEL.
 21
>22 exports.hello = function() {
 23  return 'bonjour depuis le module';
 24 };
debug>

Il est également possible de définir un point d’arrêt conditionnel qui ne s’interrompt que lorsqu’une expression donnée est évaluée à true :

$ node inspect main.js
< Débogueur à l'écoute sur ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
< Pour obtenir de l'aide, consultez : https://nodejs.org/en/docs/inspector
<
connexion à 127.0.0.1:9229... ok
< Débogueur attaché.
Point d'arrêt au démarrage dans 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
Point d'arrêt dans main.js:4
  2
  3 function addOne(num) {
> 4  return num + 1;
  5 }
  6
debug> exec('num')
-1
debug>

Information

• backtrace, bt: Afficher la pile d'exécution du frame courant
• list(5): Afficher le code source du script avec un contexte de 5 lignes (5 lignes avant et après)
• watch(expr): Ajouter une expression à la liste de surveillance
• unwatch(expr): Supprimer une expression de la liste de surveillance
• unwatch(index): Supprimer l'expression à un index spécifique de la liste de surveillance
• watchers: Afficher tous les observateurs et leurs valeurs (automatiquement affichés à chaque point d'arrêt)
• repl: Ouvrir un repl du débogueur pour évaluer dans le contexte du script en cours de débogage
• exec expr, p expr: Exécuter une expression dans le contexte du script en cours de débogage et afficher sa valeur
• profile: Démarrer une session de profilage CPU
• profileEnd: Arrêter la session de profilage CPU actuelle
• profiles: Afficher toutes les sessions de profilage CPU terminées
• profiles[n].save(filepath = 'node.cpuprofile'): Enregistrer la session de profilage CPU sur le disque au format JSON
• takeHeapSnapshot(filepath = 'node.heapsnapshot'): Prendre un instantané du tas et l'enregistrer sur le disque au format JSON

Contrôle de l'exécution

• run: Exécuter le script (s'exécute automatiquement au démarrage du débogueur)
• restart: Redémarrer le script
• kill: Arrêter le script

Divers

• scripts: Afficher tous les scripts chargés
• version: Afficher la version de V8

Utilisation avancée

Intégration de l'inspecteur V8 pour Node.js

L'intégration de l'inspecteur V8 permet de connecter Chrome DevTools aux instances Node.js pour le débogage et le profilage. Il utilise le Protocole Chrome DevTools.

L'inspecteur V8 peut être activé en passant l'option --inspect lors du démarrage d'une application Node.js. Il est également possible de fournir un port personnalisé avec cette option, par exemple --inspect=9222 acceptera les connexions DevTools sur le port 9222.

L'utilisation de l'option --inspect exécutera le code immédiatement avant que le débogueur ne soit connecté. Cela signifie que le code commencera à s'exécuter avant que vous puissiez commencer à déboguer, ce qui peut ne pas être idéal si vous souhaitez déboguer dès le début.

Dans de tels cas, vous avez deux alternatives :

Ainsi, lorsque vous choisissez entre --inspect, --inspect-wait et --inspect-brk, déterminez si vous voulez que le code commence à s'exécuter immédiatement, attende que le débogueur soit connecté avant l'exécution, ou s'arrête à la première ligne pour un débogage pas à pas.

$ 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

(Dans l'exemple ci-dessus, l'UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29 à la fin de l'URL est généré à la volée, il varie selon les différentes sessions de débogage.)

Si le navigateur Chrome est antérieur à la version 66.0.3345.0, utilisez inspector.html au lieu de js_app.html dans l'URL ci-dessus.

Chrome DevTools ne prend pas encore en charge le débogage des threads worker. ndb peut être utilisé pour les déboguer.