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/gdUnit4depuis la release GitHub (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) et activer le plugin. Les tests se placent dansres://test/, avec des noms se terminant par_test.gd. - Une suite
extends GdUnitTestSuite. Les tests sontfunc 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èsmonitor_signals(obj)),assert_error(func() -> void: ...), etawait 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"), puisrunner.simulate_action_pressed("jump"),await runner.simulate_frames(30),runner.simulate_key_pressed(KEY_SPACE),await runner.await_signal("landed"),runner.invoke("method")etrunner.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.Sdk18.x,gdUnit4.api5.1.0-rc5 (l'adaptateur 3.1.1 nécessite ≥5.1.0-rc5 ; 5.0.0 échoue la restauration avec NU1605),gdUnit4.test.adapter3.1.1,gdUnit4.analyzers1.0.0, plus<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>. - Ajouter un
.runsettingsavec<GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>. Sans cela, les tests du runtime Godot expirent lors de la connexion. Exécuter avecGODOT_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. Utiliserusing static GdUnit4.Assertions;→AssertThat(x).IsEqual(y),AutoFree(node). [RequireGodotRuntime]est obligatoire sur tout test qui touche aux types Godot, y comprisMathf, les nœuds et les ressources. L'analyseur signaleGdUnit0501sinon. 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). Trouvezuser://avecOS.get_user_data_dir(). Loggerpersonnalisé (4.5+) : sous-classez-le, surchargez_log_error/_log_message, et enregistrez-le avecOS.add_logger(). Utilisez-le pour les rapports de bugs in-game avecscript_backtraces. Activezdebug/settings/gdscript/always_track_call_stackspour 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:6007pour 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