Déboguer un test en échec avec un agent

Ce guide vous montre comment amener un agent à se servir d’un débogueur sur une défaillance que les instructions print n’expliquent pas.

L’outil debug pilote une véritable session Debug Adapter Protocol. Un cadre arrêté répond d’un coup à toutes les questions sur cet instant — chaque variable locale, chaque appelant, et une expression évaluée dans la portée propre du cadre — là où une instruction print ne répond qu’à la question que vous avez pensé à poser avant de lancer.

Avant de commencer

L’outil reste présent dans la surface d’outils, afin que l’agent puisse demander pourquoi rien n’est utilisable plutôt que de deviner. Un adaptateur ne peut réellement démarrer que si ces deux conditions sont réunies :

• un marqueur de projet dans le checkout, et
• le binaire de l’adaptateur qui se résout.

Demandez à l’agent de vérifier :

debug(op: "adapters")

Il répond avec ce qu’il a trouvé, ou explique qu’un adaptateur a besoin des deux moitiés.

Langage	Adaptateur	Marqueur	Installation
Dart / Flutter	dart debug_adapter	pubspec.yaml	Fourni avec le SDK — rien à faire
Python	python3 -m debugpy.adapter	pyproject.toml, setup.py, requirements.txt	pip install debugpy
Rust / C / C++	lldb-dap	Cargo.toml, CMakeLists.txt	Fourni avec LLVM
Go	dlv dap	go.mod	go install github.com/go-delve/delve/cmd/dlv@latest

Python choisit l’interpréteur du projet

debugpy est recherché dans .venv/bin ou venv/bin avant $PATH. Un python du $PATH est un autre environnement, et s’attacher depuis le mauvais échoue d’une manière qui se lit comme du code cassé plutôt que comme le mauvais interpréteur.

Posez d’abord le point d’arrêt, puis lancez

L’ordre compte et l’outil l’impose : les points d’arrêt peuvent être posés avant qu’une session existe, car c’est la séquence qu’exige le protocole.

Demandez à l’agent quelque chose comme :

La fonction compute dans bin/main.dart renvoie une valeur erronée. Posez un point d’arrêt sur la ligne qui affecte product, lancez-le sous le débogueur et dites-moi ce que valent réellement a et b.

Il exécutera à peu près :

debug(op: "breakpoints", file: "bin/main.dart", lines: [7])
debug(op: "launch", program: "bin/main.dart")

Le lancement indique où il s’est arrêté :

Launched bin/main.dart on dart (session dart-1). Stopped: breakpoint. Use `stack` to see where.

S’il signale à la place que le programme se termine

Le point d’arrêt ne s’est pas fixé. Une ligne vide, un commentaire ou une ligne non compilée dans le build ne peut pas en porter un. Appeler breakpoints sur une session active indique combien de ceux que vous avez posés ont réellement été placés.

Lisez le cadre

debug(op: "stack")
→ #1 compute (bin/main.dart:7:3)
  #2 main (bin/main.dart:2:18)

Puis descendez dedans :

debug(op: "scopes", frame_id: 1)
→ Locals (reference 12)

debug(op: "variables", reference: 12)
→ a (int) = 6
  b (int) = 7
  product (int) = 42

Un objet qui a des enfants indique [expand: reference N] — mais uniquement lorsqu’il y a réellement quelque chose derrière, si bien qu’une expansion inutilisable par l’agent n’est jamais proposée.

Pour tout ce qui n’apparaît pas comme variable locale :

debug(op: "evaluate", expression: "config.timeout.inSeconds", frame_id: 1)

Avancez pas à pas

Ce que vous voulez	Opération
Exécuter jusqu’au prochain arrêt	continue
Ligne suivante, même cadre	step_over
Entrer dans l’appel	step_in
Sortir vers l’appelant	step_out
Arrêter un programme en cours	pause

S’attacher à un processus déjà en cours

Pour un processus bloqué plutôt qu’un processus que vous lancez :

debug(op: "attach", port: 5858)

Terminer

debug(op: "terminate")

Terminez toujours la session. Un adaptateur de débogage possède un processus arrêté qui retient tout ce que ce processus retient — un port, un verrou, une connexion à une base de données.

Il ne peut pas vous échapper

Chaque session a une durée de vie stricte qu’elle ne peut pas prolonger, il en existe exactement une par conversation, et tout est démonté à l’arrêt du serveur. Un second launch est refusé plutôt que de remplacer le premier : un agent qui en démarre un sans terminer l’autre a presque certainement perdu la trace du premier.

Sortie bornée

Une expansion variables sur un graphe d’objets profond est par nature non bornée — un seul widget Flutter atteint tout l’arbre d’éléments. Les enfants par portée sont plafonnés à 50, les valeurs à 400 caractères et les cadres de pile à 30. Un résultat d’outil qui remplit la fenêtre de contexte est un outil qui met fin à l’exécution qu’il aidait.

Voir aussi

• Intelligence du code — pourquoi un débogueur, un compilateur et un moteur de correspondance répondent à des questions différentes
• Outils d’agent intégrés — chaque opération et chaque argument de debug
• Diagnostiquer un agent — quand le problème est l’agent, et non le code