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/gdUnit4do release do GitHub (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) e ative o plugin. Os testes vão emres://test/, com nomes terminando em_test.gd. - Uma suite
extends GdUnitTestSuite. Os testes sãofunc 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ósmonitor_signals(obj)),assert_error(func() -> void: ...), eawait 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"), depoisrunner.simulate_action_pressed("jump"),await runner.simulate_frames(30),runner.simulate_key_pressed(KEY_SPACE),await runner.await_signal("landed"),runner.invoke("method")erunner.scene(). - CLI (o que
test_run.pychama):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.Sdk18.x,gdUnit4.api5.1.0-rc5 (adapter 3.1.1 requer ≥5.1.0-rc5; 5.0.0 falha no restore com NU1605),gdUnit4.test.adapter3.1.1,gdUnit4.analyzers1.0.0, mais<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>. - Adicione um
.runsettingscom<GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>. Sem ele, os testes do runtime Godot excedem o tempo limite de conexão. Execute comGODOT_BIN=<godot exe> dotnet test --settings .runsettings. - Classes
[TestSuite], métodos[TestCase],[Before]/[After]/[BeforeTest]/[AfterTest],[DataPoint(nameof(Cases))]para testes parametrizados. Useusing static GdUnit4.Assertions;→AssertThat(x).IsEqual(y),AutoFree(node). [RequireGodotRuntime]é necessário em qualquer teste que toque em tipos do Godot, incluindoMathf, nós e recursos. Caso contrário, o analisador reportaGdUnit0501. 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). Encontreuser://comOS.get_user_data_dir(). - Logger personalizado (4.5+): crie uma subclasse, sobrescreva
_log_error/_log_messagee registre comOS.add_logger(). Use para relatórios de bugs no jogo comscript_backtraces. Ativedebug/settings/gdscript/always_track_call_stackspara backtraces em builds de release.Engine.capture_script_backtraces()captura um sob demanda. - CLI:
-d(depurador stdout),--verbose,--debug-collisions/--debug-navigatione--remote-debug tcp://host:6007para 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