CommunityProgramación y desarrollogithub.com

godot-testing-debug

Prueba y depura proyectos de Godot 4.7: GdUnit4 (GDScript) y gdUnit4Net (C#) con versiones verificadas, pruebas unitarias/de escenas, mocks, aserciones de señales, simulación de entrada, ejecuciones headless en JSON, depurador, puntos de interrupción, Logger personalizado, backtraces y lectura de errores. Úsalo al escribir o ejecutar pruebas, o al rastrear bugs y crashes.

¿Qué es godot-testing-debug?

Esta skill proporciona un flujo de trabajo completo de testing y depuración para Godot 4.7, cubriendo tanto GDScript como C#. Incluye scripts de automatización que compilan, ejecutan pruebas en modo headless y devuelven resultados en JSON. Soporta GdUnit4 (versión verificada 6.2.2) para GDScript y gdUnit4Net (con versiones concretas de paquetes NuGet) para C#, incluyendo pruebas unitarias, ejecutores de escenas, mocks, aserciones de señales y simulación de entrada por teclado/acción. La depuración abarca el depurador del editor, logging personalizado (Logger), backtraces en builds de release y métodos rápidos para interpretar errores comunes. También incluye un patrón de Logger en juego que las pruebas pueden compilar. Es ideal para desarrolladores que necesitan escribir o ejecutar pruebas de forma consistente, o rastrear bugs y crashes en Godot 4.7.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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/gdUnit4 desde el release de GitHub (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) y habilita el plugin. Las pruebas van en res://test/, con nombres que terminan en _test.gd.
  • Una suite extends GdUnitTestSuite. Las pruebas son func 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 de monitor_signals(obj)), assert_error(func() -> void: ...), y await 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"), luego runner.simulate_action_pressed("jump"), await runner.simulate_frames(30), runner.simulate_key_pressed(KEY_SPACE), await runner.await_signal("landed"), runner.invoke("method") y runner.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.Sdk 18.x, gdUnit4.api 5.1.0-rc5 (el adaptador 3.1.1 requiere ≥5.1.0-rc5; 5.0.0 falla en restore con NU1605), gdUnit4.test.adapter 3.1.1, gdUnit4.analyzers 1.0.0, más <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>.
  • Agrega un .runsettings con <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 con GODOT_BIN=<godot exe> dotnet test --settings .runsettings.
  • Clases [TestSuite], métodos [TestCase], [Before]/[After]/[BeforeTest]/[AfterTest], [DataPoint(nameof(Cases))] para pruebas parametrizadas. Usa using static GdUnit4.Assertions; → AssertThat(x).IsEqual(y), AutoFree(node).
  • [RequireGodotRuntime] es obligatorio en cualquier prueba que toque tipos de Godot, incluyendo Mathf, nodos y recursos. El analizador reporta GdUnit0501 en 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). Encuentra user:// con OS.get_user_data_dir().
  • Logger personalizado (4.5+): crea una subclase, sobreescribe _log_error/_log_message, y registra con OS.add_logger(). Úsalo para reportes de bugs en el juego con script_backtraces. Activa debug/settings/gdscript/always_track_call_stacks para 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:6007 para 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

Individual skills in this repo

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

Skills relacionados