godot-testing-debug

Tester et déboguer des projets Godot 4.7 – GdUnit4 (GDScript) et gdUnit4Net (C#) avec versions vérifiées, tests unitaires/scène-runner, mocks, assertions de signaux, simulation d’entrées, exécutions headless au format JSON, débogueur, points d’arrêt, Logger personnalisé, backtraces, lecture des erreurs. À utiliser lors de l’écriture ou de l’exécution de tests, ou pour traquer les bugs et les plantages.

Qu'est-ce que godot-testing-debug ?

Cette compétence spécialisée fournit un guide complet pour tester et déboguer des projets Godot 4.7 en implémentant GdUnit4 pour GDScript et gdUnit4Net pour C#. Elle inclut l’exécution de tests avec un script Python (`test_run.py`) qui importe le projet, le lance en mode headless et parse les résultats JUnit/console en JSON. Le guide détaille les fonctionnalités avancées de test : assertions (types, signaux, erreurs), doubles (mocks, spy, verify), scène-runner pour tests d’intégration, tests paramétrés en C#, et l’exigence de l’attribut `[RequireGodotRuntime]` pour les tests touchant le moteur. Pour le débogage, il couvre le débogueur éditeur, les points d’arrêt, l’inspection d’arbres de scène, le logging personnalisé (surcharge de `Logger`), les logs fichier, les arguments CLI (`-d`, `--verbose`, `--remote-debug`), et l’attachement de débogueur IDE pour C#. Enfin, il offre des techniques de lecture rapide des erreurs (pointeurs de fichier/ligne, causes fréquentes comme `null instance` ou `previously freed`) et des conseils de conception pour des suites de test rapides et efficaces, avec des références vers `references/patterns.md`.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/EL4CTEO/godot-skills/tree/main/skills/godot-testing-debug

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Test et débogage (4.7)

Exécuter les tests : python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] retourne {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}}. Le script importe d'abord, exécute en mode headless, puis parse les résultats JUnit/console. Avant les tests, compiler avec : ../godot-gdscript/scripts/gd_check.py et ../godot-csharp/scripts/cs_build.py. Effectuer un lancement de test du jeu avec ../godot-core/scripts/run_godot.py smoke.

GDScript : GdUnit4 (vérifié 6.2.2 sur 4.7.2)

  • Installation : copier addons/gdUnit4 depuis la release GitHub (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) et activer le plugin. Les tests se placent dans res://test/, avec des noms se terminant par _test.gd.
  • Une suite extends GdUnitTestSuite. Les tests sont func test_*(). Hooks : before(), after() (par suite), before_test(), after_test().
  • Assertions : assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...), assert_that(x), assert_signal(obj).is_emitted("died") (après monitor_signals(obj)), assert_error(func() -> void: ...), et await assert_func(obj, "is_ready").is_true().
  • Mémoire : envelopper les objets créés dans auto_free(...). Le rapport signale les nœuds orphelins, à traiter comme des bugs.
  • Doubles : mock(Class) + do_return(v).on(m).method(), spy(instance), verify(m, times).method(args), any_int() et autres.
  • Intégration : var runner := scene_runner("res://player.tscn"), puis runner.simulate_action_pressed("jump"), await runner.simulate_frames(30), runner.simulate_key_pressed(KEY_SPACE), await runner.await_signal("landed"), runner.invoke("method") et runner.scene().
  • CLI (ce qu'appelle test_run.py) : godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test. Le code de sortie 0 signifie succès et 100 signifie échecs. Les rapports sont au format JUnit XML dans le répertoire -rd.

C# : gdUnit4Net (vérifié avec Godot.NET.Sdk 4.7.2, .NET 10 SDK)

  • Ajouter au csproj du jeu : Microsoft.NET.Test.Sdk 18.x, gdUnit4.api 5.1.0-rc5 (l'adaptateur 3.1.1 nécessite ≥5.1.0-rc5 ; 5.0.0 échoue la restauration avec NU1605), gdUnit4.test.adapter 3.1.1, gdUnit4.analyzers 1.0.0, plus <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>.
  • Ajouter un .runsettings avec <GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>. Sans cela, les tests du runtime Godot expirent lors de la connexion. Exécuter avec GODOT_BIN=<godot exe> dotnet test --settings .runsettings.
  • Classes [TestSuite], méthodes [TestCase], [Before]/[After]/[BeforeTest]/[AfterTest], [DataPoint(nameof(Cases))] pour les tests paramétrés. Utiliser using static GdUnit4.Assertions; → AssertThat(x).IsEqual(y), AutoFree(node).
  • [RequireGodotRuntime] est obligatoire sur tout test qui touche aux types Godot, y compris Mathf, les nœuds et les ressources. L'analyseur signale GdUnit0501 sinon. Les tests C# purs s'exécutent sans le moteur et sont beaucoup plus rapides.
  • Scènes : ISceneRunner.Load("res://x.tscn") → SimulateFrames, SimulateActionPressed, AwaitSignal, Invoke.

Ce qu'il faut tester

La logique pure (dégâts, inventaire, migration de sauvegarde) comme tests unitaires rapides. Les scènes via des scène-runners pour le ressenti des contrôleurs, les flux UI et le câblage de signaux. Chaque correction de bug s'accompagne d'un test de régression. Gardez les suites rapides, car les suites lentes finissent par ne plus être exécutées.

Débogage

  • Exécuter depuis l'éditeur (F5) pour le débogueur complet : erreurs avec traces de pile, points d'arrêt (ou une instruction breakpoint), pas à pas entrant/sortant (Step Out arrivé en 4.6), l'arbre de scène Distant (inspection en direct des nœuds et propriétés pendant l'exécution), le Profileur, les Moniteurs et les instantanés ObjectDB (4.6).
  • Journalisation : print, print_rich("[color=yellow]..."), print_debug (ajoute fichier et ligne), push_warning/push_error (affichés dans le débogueur avec une trace, non fatals), printerr. assert(cond, "msg") ne s'exécute que dans les builds de débogage, donc ne mettez jamais d'effets de bord à l'intérieur.
  • Journaux fichiers : debug/file_logging/enable_file_logging (activé par défaut pour le bureau, user://logs/godot.log). Trouvez user:// avec OS.get_user_data_dir().
  • Logger personnalisé (4.5+) : sous-classez-le, surchargez _log_error/_log_message, et enregistrez-le avec OS.add_logger(). Utilisez-le pour les rapports de bugs in-game avec script_backtraces. Activez debug/settings/gdscript/always_track_call_stacks pour les backtraces en build de release. Engine.capture_script_backtraces() en capture une à la demande.
  • CLI : -d (débogueur stdout), --verbose, --debug-collisions/--debug-navigation, et --remote-debug tcp://host:6007 pour attacher un build en cours d'exécution à l'éditeur.
  • C# : attachez un débogueur IDE au processus du jeu (Rider et C# Dev Kit de VS Code peuvent lancer Godot avec --path). Les exceptions sont journalisées, non fatales, donc surveillez le panneau de sortie.

Lire les erreurs rapidement

res://fichier.gd:LIGNE pointe vers la ligne. "null instance" signifie un mauvais chemin de nœud ou quelque chose utilisé avant _ready. "previously freed" signifie qu'un await ou un callback a survécu à son nœud. Une "Parse Error" ou "Compile Error" empêche le chargement du script, donc tout ce qui l'utilise échoue, et on corrige la première erreur en premier. "Condition "!is_inside_tree()" is true" signifie qu'une API d'arbre a été appelée sur un nœud qui n'est pas encore dans l'arbre. Les références aux fichiers C++ du moteur (scene/main/node.cpp:123) indiquent toujours que votre appel était erroné, donc lisez la pile.

Suites GdUnit (unitaires, mocks, signaux, scène-runner), tests C#, Logger in-game (compilé par les tests) : references/patterns.md

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Skills associés