Utilisation du débogueur intégré de Node.js

Introduction au débogueur en ligne de commande

Node.js est fourni avec un débogueur intégré accessible directement depuis la ligne de commande (CLI). Cet outil, bien que moins visuel que les interfaces graphiques comme Chrome DevTools, offre un moyen puissant et léger d'inspecter l'exécution de votre code, de poser des points d'arrêt et d'examiner l'état de votre application à des moments précis. Il repose sur le protocole de débogage V8 et constitue une excellente option pour des diagnostics rapides ou lorsque vous travaillez dans des environnements sans interface graphique (comme un serveur via SSH).

Le principe fondamental est d'exécuter votre script Node.js dans un mode spécial qui permet au débogueur de s'y attacher et de contrôler son exécution. Une fois en mode débogage, vous interagissez avec votre script via une interface textuelle, en tapant des commandes spécifiques pour naviguer dans le code, inspecter les variables, et bien plus encore.

Comprendre le fonctionnement de ce débogueur CLI est également utile car il partage les mêmes mécanismes sous-jacents que les débogueurs graphiques plus avancés. Maîtriser ses commandes de base vous donnera une meilleure compréhension du processus de débogage en général, même si vous préférez ensuite utiliser des outils plus visuels pour des tâches complexes.

Lancer une session de débogage

La manière la plus directe de démarrer une session de débogage avec l'outil intégré est d'utiliser le mot-clé `inspect` avant le nom de votre script dans la ligne de commande :

node inspect votre_script.js

Lorsque vous lancez cette commande, Node.js démarre votre script mais s'arrête immédiatement avant la première ligne de code exécutable. Vous verrez apparaître une invite `debug>` dans votre terminal, indiquant que le débogueur est actif et attend vos instructions.

Une autre approche consiste à insérer l'instruction `debugger;` directement dans votre code source JavaScript, là où vous souhaitez que l'exécution s'arrête. C'est l'équivalent d'un point d'arrêt codé en dur.

// votre_script.js
console.log('Début du script');

let x = 10;
let y = 20;

debugger; // L'exécution s'arrêtera ici lorsque lancé avec 'inspect'

let somme = x + y;
console.log(`La somme est : ${somme}`);

console.log('Fin du script');

Si vous lancez `node inspect votre_script.js` avec ce code, l'exécution se poursuivra jusqu'à la ligne `debugger;` puis s'arrêtera, vous donnant l'invite `debug>`.

Il est important de noter que la commande `node inspect` lance à la fois votre script et le client de débogage CLI dans le même processus. Vous verrez également des commandes comme `node --inspect` et `node --inspect-brk`. Celles-ci lancent votre script avec le serveur de débogage activé, mais attendent qu'un client externe (comme Chrome DevTools ou le client CLI `node inspect` séparé) s'y connecte. `inspect-brk` met en pause l'exécution dès la première ligne, tandis que `--inspect` laisse le script démarrer normalement jusqu'à ce qu'un point d'arrêt soit atteint ou qu'un client se connecte et mette en pause. Nous explorerons l'utilisation de `--inspect` avec des clients externes dans la section suivante.

Naviguer et inspecter avec les commandes du débogueur

Une fois à l'invite `debug>`, plusieurs commandes vous permettent de contrôler l'exécution et d'inspecter l'état de votre application. Voici les plus courantes :

• `cont` ou `c` : Continue l'exécution jusqu'au prochain point d'arrêt (instruction `debugger;` ou point d'arrêt défini dynamiquement) ou jusqu'à la fin du script.
• `next` ou `n` : Exécute la ligne de code suivante (Step Over). Si la ligne contient un appel de fonction, la fonction est exécutée entièrement sans y entrer.
• `step` ou `s` : Exécute la ligne de code suivante (Step Into). Si la ligne contient un appel de fonction, le débogueur entre dans cette fonction et s'arrête à sa première ligne.
• `out` ou `o` : Termine l'exécution de la fonction courante et s'arrête à la ligne suivant l'appel de cette fonction (Step Out).
• `pause` : Met en pause l'exécution du script (utile si le script est en cours d'exécution après une commande `cont`).

Pour examiner l'état de votre application, vous pouvez utiliser :

• `repl` : Passe en mode REPL (Read-Eval-Print Loop). Dans ce mode, vous pouvez taper des expressions JavaScript (noms de variables, appels de fonctions simples) qui seront évaluées dans le contexte actuel (scope) de votre code arrêté. C'est très utile pour vérifier la valeur des variables. Tapez `Ctrl+C` pour quitter le mode REPL et revenir à l'invite `debug>`.
• `watch('expression')` : Ajoute une expression à la liste des "watch expressions". La valeur de cette expression sera affichée à chaque fois que l'exécution s'arrête. Par exemple, `watch('x')` affichera la valeur de `x`.
• `unwatch('expression')` : Retire une expression de la liste des watch expressions.
• `watchers` : Affiche la liste des expressions actuellement surveillées et leurs valeurs.

D'autres commandes utiles incluent :

• `setBreakpoint()` ou `sb()` : Définit un point d'arrêt. Par exemple, `sb('votre_script.js', 10)` pose un point d'arrêt à la ligne 10 du fichier. `sb('maFonction')` pose un point d'arrêt au début de `maFonction`.
• `clearBreakpoint()` ou `cb()` : Supprime un point d'arrêt. Par exemple, `cb('votre_script.js', 10)`.
• `breakpoints` : Liste tous les points d'arrêt actifs.
• `list(n)` : Affiche `n` lignes de code source autour de la ligne actuelle.
• `restart` : Redémarre l'exécution du script depuis le début, en conservant les points d'arrêt définis.
• `.exit` : Quitte le débogueur.

Exemple d'une session simple

Reprenons notre script avec l'instruction `debugger;` :

// votre_script.js
console.log('Début du script');

let x = 10;
let y = 20;

debugger; // L'exécution s'arrêtera ici

let somme = x + y;
console.log(`La somme est : ${somme}`);

console.log('Fin du script');

Lançons-le avec `node inspect votre_script.js` :

$ node inspect votre_script.js
< Debugger listening on ws://127.0.0.1:9229/...
< For help, see: https://nodejs.org/en/docs/inspector
< Debugger attached.
Break on start in votre_script.js:1
> 1 console.log('Début du script');
  2
  3 let x = 10;
debug> c  # On continue jusqu'au debugger;
break in votre_script.js:7
  5 let y = 20;
  6
> 7 debugger; // L'exécution s'arrêtera ici
  8
  9 let somme = x + y;
debug> repl # On passe en mode REPL
Press Ctrl+C to leave debug repl
> x
10
> y
20
> typeof somme
'undefined' # somme n'est pas encore définie
> (Ctrl+C) # On quitte le REPL
debug> n # On passe à la ligne suivante
break in votre_script.js:9
  7 debugger; // L'exécution s'arrêtera ici
  8
> 9 let somme = x + y;
 10 console.log(`La somme est : ${somme}`);
 11
debug> repl
Press Ctrl+C to leave debug repl
> somme
30
> (Ctrl+C)
debug> c # On continue jusqu'à la fin
< La somme est : 30
< Fin du script
program terminated
debug> .exit

Cet exemple illustre comment utiliser `c`, `n` et `repl` pour suivre l'exécution pas à pas et inspecter les valeurs des variables à différents moments.

Limites et cas d'utilisation

Le débogueur intégré en ligne de commande est un outil efficace pour des tâches de débogage simples et rapides. Cependant, il présente certaines limites par rapport aux interfaces graphiques. L'inspection d'objets complexes ou de structures de données imbriquées peut être fastidieuse dans le REPL. La visualisation de la pile d'appels (call stack) ou la navigation dans des projets avec de nombreux fichiers sont moins intuitives qu'avec des outils visuels.

Malgré ces limitations, il reste très pertinent dans plusieurs scénarios :

• Débogage rapide : Pour vérifier rapidement la valeur d'une variable ou le chemin d'exécution dans un script simple.
• Environnements sans GUI : Indispensable lors du débogage sur des serveurs distants via SSH où une interface graphique n'est pas disponible.
• Apprentissage : Utiliser le débogueur CLI aide à comprendre les concepts fondamentaux du débogage (points d'arrêt, pas à pas, inspection) qui s'appliquent aussi aux outils plus avancés.
• Scripts simples : Pour des scripts courts ou des utilitaires en ligne de commande, il est souvent suffisant et évite d'avoir à configurer un environnement de débogage plus complexe.

Pour des applications plus conséquentes, des flux de débogage complexes ou une analyse visuelle approfondie de l'état de l'application, l'utilisation d'un client de débogage graphique connecté via le protocole d'inspection (`node --inspect`) est généralement plus productive. C'est ce que nous aborderons dans la section suivante avec l'utilisation des Chrome DevTools.