Pruebas y depuración (4.7)
Ejecutar pruebas: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] devuelve {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}}. Primero importa, ejecuta en modo headless y analiza los resultados JUnit/consola.
Antes de las pruebas, compila: ../godot-gdscript/scripts/gd_check.py y ../godot-csharp/scripts/cs_build.py. Haz una ejecución rápida del juego con ../godot-core/scripts/run_godot.py smoke.
GDScript: GdUnit4 (verificado 6.2.2 en 4.7.2)
- Instalación: copia
addons/gdUnit4desde el release de GitHub (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) y habilita el plugin. Las pruebas van enres://test/, con nombres que terminan en_test.gd. - Una suite
extends GdUnitTestSuite. Las pruebas sonfunc test_*(). Hooks:before(),after()(por suite),before_test(),after_test(). - Aserciones:
assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...),assert_that(x),assert_signal(obj).is_emitted("died")(después demonitor_signals(obj)),assert_error(func() -> void: ...), yawait assert_func(obj, "is_ready").is_true(). - Memoria: envuelve los objetos creados en
auto_free(...). El reporte marca nodos huérfanos, así que trátalos como bugs. - Dobles:
mock(Class)+do_return(v).on(m).method(),spy(instance),verify(m, times).method(args),any_int()y similares. - Integración:
var runner := scene_runner("res://player.tscn"), luegorunner.simulate_action_pressed("jump"),await runner.simulate_frames(30),runner.simulate_key_pressed(KEY_SPACE),await runner.await_signal("landed"),runner.invoke("method")yrunner.scene(). - CLI (lo que llama
test_run.py):godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test. Código de salida 0 significa éxito y 100 significa fallos. Los reportes son XML JUnit en el directorio-rd.
C#: gdUnit4Net (verificado con Godot.NET.Sdk 4.7.2, .NET 10 SDK)
- Agrega al csproj del juego:
Microsoft.NET.Test.Sdk18.x,gdUnit4.api5.1.0-rc5 (el adaptador 3.1.1 requiere ≥5.1.0-rc5; 5.0.0 falla en restore con NU1605),gdUnit4.test.adapter3.1.1,gdUnit4.analyzers1.0.0, más<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>. - Agrega un
.runsettingscon<GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>. Sin esto, las pruebas que usan el runtime de Godot agotan el tiempo de conexión. Ejecuta conGODOT_BIN=<godot exe> dotnet test --settings .runsettings. - Clases
[TestSuite], métodos[TestCase],[Before]/[After]/[BeforeTest]/[AfterTest],[DataPoint(nameof(Cases))]para pruebas parametrizadas. Usausing static GdUnit4.Assertions;→AssertThat(x).IsEqual(y),AutoFree(node). [RequireGodotRuntime]es obligatorio en cualquier prueba que toque tipos de Godot, incluyendoMathf, nodos y recursos. El analizador reportaGdUnit0501en caso contrario. Las pruebas de C# puro se ejecutan sin el motor y mucho más rápido.- Escenas:
ISceneRunner.Load("res://x.tscn")→SimulateFrames,SimulateActionPressed,AwaitSignal,Invoke.
Qué probar
Lógica pura (daño, inventario, migración de guardado) como pruebas unitarias rápidas. Escenas a través de ejecutores de escena para sentir el controlador, flujos de UI y cableado de señales. Cada corrección de bug obtiene una prueba de regresión. Mantén las suites rápidas, porque las suites lentas dejan de ejecutarse.
Depuración
- Ejecuta desde el editor (F5) para el depurador completo: errores con trazas de pila, puntos de interrupción (o una sentencia
breakpoint), paso a paso por dentro/fuera (Step Out llegó en 4.6), el árbol de escenas Remoto (inspección en vivo de nodos y propiedades mientras se reproduce), el Perfilador, los Monitores y las instantáneas de ObjectDB (4.6). - Logging:
print,print_rich("[color=yellow]..."),print_debug(agrega archivo y línea),push_warning/push_error(se muestran en el depurador con una pila, y no son fatales),printerr.assert(cond, "msg")solo se ejecuta en builds de depuración, así que nunca pongas efectos secundarios dentro. - Logs en archivo:
debug/file_logging/enable_file_logging(activado por defecto en escritorio,user://logs/godot.log). Encuentrauser://conOS.get_user_data_dir(). - Logger personalizado (4.5+): crea una subclase, sobreescribe
_log_error/_log_message, y registra conOS.add_logger(). Úsalo para reportes de bugs en el juego conscript_backtraces. Activadebug/settings/gdscript/always_track_call_stackspara trazas de pila en builds de release.Engine.capture_script_backtraces()captura una a pedido. - CLI:
-d(depurador en stdout),--verbose,--debug-collisions/--debug-navigation, y--remote-debug tcp://host:6007para conectar una build en ejecución al editor. - C#: conecta un depurador del IDE al proceso del juego (Rider y C# Dev Kit de VS Code pueden lanzar Godot con
--path). Las excepciones se registran, no son fatales, así que vigila el panel de Salida.
Lectura rápida de errores
res://file.gd:LINE apunta a la línea. "null instance" significa una ruta de nodo incorrecta o algo usado antes de _ready. "previously freed" significa que un await o callback sobrevivió a su nodo. Un "Parse Error" o "Compile Error" detiene la carga del script, por lo que todo lo que lo usa falla, y debes corregir el primer error primero. "Condition "!is_inside_tree()" is true" significa que se llamó a una API de árbol en un nodo que aún no está en el árbol. Las referencias de archivos C++ del motor (scene/main/node.cpp:123) siguen indicando que tu llamada fue incorrecta, así que lee la pila.
Suites de GdUnit (unitarias, mocks, señales, ejecutor de escenas), pruebas C#, Logger en juego (compilado por las pruebas): references/patterns.md