CommunityCodierung & Entwicklunggithub.com

godot-testing-debug

Testen und Debuggen von Godot 4.7 Projekten – GdUnit4 (GDScript) und gdUnit4Net (C#) mit verifizierten Versionen, Unit-/Scene-Runner-Tests, Mocks, Signal-Asserts, Eingabesimulation, Headless-Durchläufen als JSON, Debugger, Breakpoints, benutzerdefiniertem Logger, Backtraces und Fehleranalyse. Verwenden Sie es beim Schreiben oder Ausführen von Tests oder beim Aufspüren von Bugs und Abstürzen.

Was ist godot-testing-debug?

Diese Skill-Anleitung beschreibt detailliert, wie Godot 4.7 Projekte mit GdUnit4 (GDScript) und gdUnit4Net (C#) getestet und gedeubugt werden. Sie enthält Anweisungen zum Einrichten der Test-Frameworks, zum Schreiben von Unit-Tests, zur Verwendung von Scene-Runnern für Integrationstests, zum Mocken von Objekten und zum Prüfen von Signalen. Für GDScript wird GdUnit4 in Version 6.2.2 auf Godot 4.7.2 verwendet, für C# die Pakete `gdUnit4.api` 5.1.0-rc5 und `gdUnit4.test.adapter` 3.1.1 mit .NET 10 SDK. Der Debugging-Teil behandelt den integrierten Editor-Debugger, Breakpoints, benutzerdefinierte Logger (ab Godot 4.5), CLI-Debug-Optionen und das Anhängen eines IDE-Debuggers für C#. Die Anleitung gibt außerdem Tipps zum schnellen Lesen von Fehlermeldungen und erklärt häufige Fehlerursachen wie 'null instance' oder 'previously freed'.

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

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Testen und Debuggen (4.7)

Tests ausführen: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] gibt {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}} zurück. Es importiert zuerst, führt headless aus und parst die JUnit-/Konsolenergebnisse. Vor den Tests kompilieren: ../godot-gdscript/scripts/gd_check.py und ../godot-csharp/scripts/cs_build.py. Ein Probelauf des Spiels mit ../godot-core/scripts/run_godot.py smoke.

GDScript: GdUnit4 (verifiziert 6.2.2 auf 4.7.2)

  • Installation: Kopieren Sie addons/gdUnit4 aus dem GitHub-Release (github.com/godot-gdunit-labs/gdUnit4, Tag v6.2.x) und aktivieren Sie das Plugin. Tests liegen in res://test/ und haben Namen, die auf _test.gd enden.
  • Eine Suite extends GdUnitTestSuite. Tests sind func test_*(). Hooks: before(), after() (pro 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") (nach monitor_signals(obj)), assert_error(func() -> void: ...) und await assert_func(obj, "is_ready").is_true().
  • Speicher: Erstellte Objekte in auto_free(...) verpacken. Der Bericht kennzeichnet verwaiste Nodes, behandeln Sie sie als Bugs.
  • Doubles: mock(Klasse) + do_return(wert).on(m).method(), spy(instanz), verify(m, mal).method(args), any_int() und ähnliche.
  • Integration: var runner := scene_runner("res://player.tscn"), dann runner.simulate_action_pressed("jump"), await runner.simulate_frames(30), runner.simulate_key_pressed(KEY_SPACE), await runner.await_signal("landed"), runner.invoke("method") und runner.scene().
  • CLI (was test_run.py aufruft): godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test. Exit-Code 0 bedeutet bestanden, 100 bedeutet Fehlschläge. Berichte sind JUnit-XML im -rd-Verzeichnis.

C#: gdUnit4Net (verifiziert mit Godot.NET.Sdk 4.7.2, .NET 10 SDK)

  • Fügen Sie der csproj-Datei des Spiels hinzu: Microsoft.NET.Test.Sdk 18.x, gdUnit4.api 5.1.0-rc5 (Adapter 3.1.1 benötigt ≥5.1.0-rc5; 5.0.0 schlägt bei der Wiederherstellung mit NU1605 fehl), gdUnit4.test.adapter 3.1.1, gdUnit4.analyzers 1.0.0, plus <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>.
  • Fügen Sie eine .runsettings-Datei mit <GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4> hinzu. Ohne diese Datei kommt es bei Godot-Runtime-Tests zu Zeitüberschreitungen bei der Verbindung. Ausführen mit GODOT_BIN=<godot exe> dotnet test --settings .runsettings.
  • [TestSuite]-Klassen, [TestCase]-Methoden, [Before]/[After]/[BeforeTest]/[AfterTest], [DataPoint(nameof(Cases))] für parametrisierte Tests. Verwenden Sie using static GdUnit4.Assertions; → AssertThat(x).IsEqual(y), AutoFree(node).
  • [RequireGodotRuntime] ist für jeden Test erforderlich, der Godot-Typen verwendet, einschließlich Mathf, Nodes und Ressourcen. Der Analyzer meldet andernfalls GdUnit0501. Reine C#-Tests laufen ohne die Engine und sind viel schneller.
  • Szenen: ISceneRunner.Load("res://x.tscn") → SimulateFrames, SimulateActionPressed, AwaitSignal, Invoke.

Was getestet werden soll

Reine Logik (Schaden, Inventar, Speichermigration) als schnelle Unit-Tests. Szenen über Scene-Runner für Controller-Gefühl, UI-Abläufe und Signalverdrahtung. Jeder Bugfix erhält einen Regressionstest. Halten Sie Suites schnell, denn langsame Suites werden nicht mehr ausgeführt.

Debuggen

  • Vom Editor aus ausführen (F5) für den vollständigen Debugger: Fehler mit Stack-Traces, Breakpoints (oder eine breakpoint-Anweisung), Schritt-für-Schritt (Step Out gibt es seit 4.6), den Remote-Szenenbaum (Live-Node- und Property-Inspektion während des Spielens), Profiler, Monitore und ObjectDB-Snapshots (4.6).
  • Logging: print, print_rich("[color=yellow]..."), print_debug (fügt Datei und Zeile hinzu), push_warning/push_error (werden im Debugger mit einem Stack und nicht tödlich angezeigt), printerr. assert(cond, "msg") läuft nur in Debug-Builds, setzen Sie daher niemals Seiteneffekte hinein.
  • Datei-Logs: debug/file_logging/enable_file_logging (standardmäßig für Desktop aktiviert, user://logs/godot.log). Finden Sie user:// mit OS.get_user_data_dir().
  • Benutzerdefinierter Logger (4.5+): Erstellen Sie eine Unterklasse, überschreiben Sie _log_error/_log_message und registrieren Sie sie mit OS.add_logger(). Verwenden Sie es für In-Game-Bug-Reports mit script_backtraces. Aktivieren Sie debug/settings/gdscript/always_track_call_stacks für Backtraces in Release-Builds. Engine.capture_script_backtraces() erfasst bei Bedarf einen.
  • CLI: -d (stdout-Debugger), --verbose, --debug-collisions/--debug-navigation und --remote-debug tcp://host:6007 um einen laufenden Build an den Editor anzuhängen.
  • C#: Hängen Sie einen IDE-Debugger an den Spielprozess an (Rider und VS Code C# Dev Kit können Godot mit --path starten). Ausnahmen werden protokolliert, sind aber nicht tödlich; achten Sie daher auf das Ausgabefenster.

Fehler schnell lesen

res://datei.gd:ZEILE zeigt auf die Zeile. "null instance" bedeutet einen falschen Node-Pfad oder etwas, das vor _ready verwendet wurde. "previously freed" bedeutet, dass ein await oder Callback seinen Node überlebt hat. Ein "Parse Error" oder "Compile Error" stoppt das Laden des Skripts, sodass alles, was es verwendet, fehlschlägt, und Sie beheben zuerst den ersten Fehler. "Condition "!is_inside_tree()" is true" bedeutet, dass eine Tree-API auf einem Node aufgerufen wurde, der noch nicht im Baum ist. Engine-C++-Dateiverweise (scene/main/node.cpp:123) bedeuten immer noch, dass Ihr Aufruf falsch war, lesen Sie also den Stack.

GdUnit-Suites (Unit, Mocks, Signale, Scene-Runner), C#-Tests, In-Game-Logger (von den Tests kompiliert): references/patterns.md

Individual skills in this repo

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

Verwandte Skills