godot-testing-debug

Teste e depure projetos Godot 4.7 - GdUnit4 (GDScript) e gdUnit4Net (C#) com versões verificadas, testes unitários/de cena, mocks, asserções de sinais, simulação de entrada, execuções headless em JSON, depurador, breakpoints, Logger personalizado, backtraces e leitura de erros. Use ao escrever ou executar testes, ou ao rastrear bugs e crashes.

O que é godot-testing-debug?

Esta habilidade fornece um guia completo para testar e depurar projetos Godot 4.7 usando as estruturas de teste GdUnit4 (para GDScript) e gdUnit4Net (para C#). Ela descreve como executar testes via um script Python que importa o projeto, executa em modo headless e retorna resultados em JSON, além dos comandos de compilação necessários. Para GDScript, detalha a instalação do plugin GdUnit4 (versão 6.2.2), asserções, doubles (mocks e spies), execução de cenas com scene runners e a CLI usada internamente. Para C#, explica a configuração do pacote NuGet gdUnit4.api (5.1.0-rc5), a necessidade do atributo `[RequireGodotRuntime]` para testes que dependem do Godot, e o uso de ISceneRunner. A habilidade também cobre estratégias de teste (unidades rápidas vs. testes de cena), depuração interativa no editor (breakpoints, Remote Scene Tree), logging (print, Logger personalizado), depuração via CLI (`-d`, `--remote-debug`) e técnicas para ler erros rapidamente, incluindo dicas para erros comuns como 'null instance' e 'previously freed'. Suporta tanto GDScript quanto C# e é aplicável em qualquer projeto Godot 4.7 que use GdUnit4/gdUnit4Net, recomendada para desenvolvedores e agentes de IA que precisam escrever, executar testes ou diagnosticar falhas.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Testes e depuração (4.7)

Executar testes: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] retorna {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}}. Ele primeiro importa, executa em modo headless e analisa os resultados JUnit/console. Antes dos testes, compile: ../godot-gdscript/scripts/gd_check.py e ../godot-csharp/scripts/cs_build.py. Execute um teste rápido do jogo com ../godot-core/scripts/run_godot.py smoke.

GDScript: GdUnit4 (verificado 6.2.2 no 4.7.2)

  • Instalação: copie addons/gdUnit4 do release do GitHub (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) e ative o plugin. Os testes vão em res://test/, com nomes terminando em _test.gd.
  • Uma suite extends GdUnitTestSuite. Os testes são func test_*(). Hooks: before(), after() (por suite), before_test(), after_test().
  • Asserções: assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...), assert_that(x), assert_signal(obj).is_emitted("died") (após monitor_signals(obj)), assert_error(func() -> void: ...), e await assert_func(obj, "is_ready").is_true().
  • Memória: envolva objetos criados em auto_free(...). O relatório sinaliza nós órfãos, então trate-os como bugs.
  • Doubles: mock(Class) + do_return(v).on(m).method(), spy(instance), verify(m, times).method(args), any_int() e amigos.
  • Integração: var runner := scene_runner("res://player.tscn"), depois runner.simulate_action_pressed("jump"), await runner.simulate_frames(30), runner.simulate_key_pressed(KEY_SPACE), await runner.await_signal("landed"), runner.invoke("method") e runner.scene().
  • CLI (o que test_run.py chama): godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test. Código de saída 0 significa sucesso e 100 significa falhas. Relatórios são XML JUnit no diretório -rd.

C#: gdUnit4Net (verificado com Godot.NET.Sdk 4.7.2, .NET 10 SDK)

  • Adicione ao csproj do jogo: Microsoft.NET.Test.Sdk 18.x, gdUnit4.api 5.1.0-rc5 (adapter 3.1.1 requer ≥5.1.0-rc5; 5.0.0 falha no restore com NU1605), gdUnit4.test.adapter 3.1.1, gdUnit4.analyzers 1.0.0, mais <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>.
  • Adicione um .runsettings com <GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>. Sem ele, os testes do runtime Godot excedem o tempo limite de conexão. Execute com GODOT_BIN=<godot exe> dotnet test --settings .runsettings.
  • Classes [TestSuite], métodos [TestCase], [Before]/[After]/[BeforeTest]/[AfterTest], [DataPoint(nameof(Cases))] para testes parametrizados. Use using static GdUnit4.Assertions; → AssertThat(x).IsEqual(y), AutoFree(node).
  • [RequireGodotRuntime] é necessário em qualquer teste que toque em tipos do Godot, incluindo Mathf, nós e recursos. Caso contrário, o analisador reporta GdUnit0501. Testes C# puros rodam sem o motor e são muito mais rápidos.
  • Cenas: ISceneRunner.Load("res://x.tscn") → SimulateFrames, SimulateActionPressed, AwaitSignal, Invoke.

O que testar

Lógica pura (dano, inventário, migração de save) como testes unitários rápidos. Cenas através de executores de cena para sensação do controle, fluxos de UI e conexões de sinais. Cada correção de bug recebe um teste de regressão. Mantenha as suítes rápidas, porque suítes lentas deixam de ser executadas.

Depuração

  • Execute pelo editor (F5) para o depurador completo: erros com stack traces, breakpoints (ou uma declaração breakpoint), entrar/sair (Step Out chegou no 4.6), a árvore de cena Remota (inspeção ao vivo de nós e propriedades durante a execução), Profiler, Monitores e snapshots do ObjectDB (4.6).
  • Logging: print, print_rich("[color=yellow]..."), print_debug (adiciona arquivo e linha), push_warning/push_error (mostrados no depurador com stack, e não fatais), printerr. assert(cond, "msg") só executa em builds de depuração, então nunca coloque efeitos colaterais dentro dele.
  • Logs de arquivo: debug/file_logging/enable_file_logging (ativado por padrão para desktop, user://logs/godot.log). Encontre user:// com OS.get_user_data_dir().
  • Logger personalizado (4.5+): crie uma subclasse, sobrescreva _log_error/_log_message e registre com OS.add_logger(). Use para relatórios de bugs no jogo com script_backtraces. Ative debug/settings/gdscript/always_track_call_stacks para backtraces em builds de release. Engine.capture_script_backtraces() captura um sob demanda.
  • CLI: -d (depurador stdout), --verbose, --debug-collisions/--debug-navigation e --remote-debug tcp://host:6007 para anexar uma build em execução ao editor.
  • C#: anexe um depurador da IDE ao processo do jogo (Rider e C# Dev Kit do VS Code podem iniciar Godot com --path). Exceções são logadas, não fatais, então fique de olho no painel de saída.

Lendo erros rapidamente

res://arquivo.gd:LINHA aponta para a linha. "null instance" significa um caminho de nó inválido ou algo usado antes de _ready. "previously freed" significa que um await ou callback sobreviveu ao seu nó. Um "Parse Error" ou "Compile Error" impede que o script carregue, então tudo que o usa falha, e você corrige o primeiro erro primeiro. "Condition "!is_inside_tree()" is true" significa que uma API de árvore foi chamada em um nó que ainda não está na árvore. Referências de arquivos C++ do motor (scene/main/node.cpp:123) ainda significam que sua chamada estava errada, então leia o stack.

Suítes GdUnit (unitárias, mocks, sinais, executor de cena), testes C#, Logger no jogo (compilado pelos testes): references/patterns.md

Individual skills in this repo

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

Habilidades Relacionadas