테스트 및 디버깅 (4.7)
테스트 실행: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] 는 {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}} 를 반환합니다. 먼저 임포트하고 헤드리스로 실행한 후 JUnit/콘솔 결과를 파싱합니다.
테스트 전에 컴파일: ../godot-gdscript/scripts/gd_check.py 및 ../godot-csharp/scripts/cs_build.py. ../godot-core/scripts/run_godot.py smoke 로 게임을 간단히 실행(smoke-run)합니다.
GDScript: GdUnit4 (4.7.2에서 6.2.2 검증됨)
- 설치: GitHub 릴리스(github.com/godot-gdunit-labs/gdUnit4, 태그 v6.2.x)에서
addons/gdUnit4를 복사하고 플러그인을 활성화합니다. 테스트는res://test/디렉토리에 넣고 파일명은_test.gd로 끝나야 합니다. - 테스트 스위트는
extends GdUnitTestSuite입니다. 테스트 메서드는func test_*()형태입니다. 훅:before(),after()(스위트별),before_test(),after_test(). - 단언:
assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...),assert_that(x),assert_signal(obj).is_emitted("died")(monitor_signals(obj)호출 후),assert_error(func() -> void: ...), 그리고await assert_func(obj, "is_ready").is_true(). - 메모리: 생성된 객체를
auto_free(...)로 감쌉니다. 리포트는 고아 노드(orphan nodes)를 플래그로 표시하므로 이를 버그로 간주하세요. - 더블(Doubles):
mock(Class)+do_return(v).on(m).method(),spy(instance),verify(m, times).method(args),any_int()및 관련 함수들. - 통합(Integration):
var runner := scene_runner("res://player.tscn")실행 후,runner.simulate_action_pressed("jump"),await runner.simulate_frames(30),runner.simulate_key_pressed(KEY_SPACE),await runner.await_signal("landed"),runner.invoke("method")및runner.scene(). - CLI (
test_run.py가 호출하는 방식):godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test. 종료 코드 0은 통과, 100은 실패를 의미합니다. 보고서는-rd디렉토리 아래 JUnit XML 형식입니다.
C#: gdUnit4Net (Godot.NET.Sdk 4.7.2, .NET 10 SDK로 검증됨)
- 게임 csproj 파일에 다음을 추가:
Microsoft.NET.Test.Sdk18.x,gdUnit4.api5.1.0-rc5 (어댑터 3.1.1은 ≥5.1.0-rc5 필요; 5.0.0은 NU1605로 복원 실패),gdUnit4.test.adapter3.1.1,gdUnit4.analyzers1.0.0, 그리고<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>. <GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>가 포함된.runsettings파일을 추가합니다. 이 설정이 없으면 Godot 런타임 테스트가 연결 시간 초과로 실패합니다.GODOT_BIN=<godot exe> dotnet test --settings .runsettings명령으로 실행합니다.[TestSuite]클래스,[TestCase]메서드,[Before]/[After]/[BeforeTest]/[AfterTest], 매개변수화된 테스트를 위한[DataPoint(nameof(Cases))].using static GdUnit4.Assertions;사용 →AssertThat(x).IsEqual(y),AutoFree(node).[RequireGodotRuntime]는 Godot 타입(Mathf, 노드, 리소스 등)을 건드리는 모든 테스트에 필수입니다. 그렇지 않으면 분석기가GdUnit0501오류를 보고합니다. 순수 C# 테스트는 엔진 없이 실행되어 훨씬 빠릅니다.- 씬(Scenes):
ISceneRunner.Load("res://x.tscn")→SimulateFrames,SimulateActionPressed,AwaitSignal,Invoke.
테스트할 대상
순수 로직(데미지, 인벤토리, 저장 마이그레이션)은 빠른 단위 테스트로. 씬은 씬 러너를 통해 컨트롤러 느낌, UI 흐름 및 시그널 연결을 테스트합니다. 모든 버그 수정에는 회귀 테스트를 추가합니다. 스위트가 느려지면 실행되지 않으므로 빠르게 유지하세요.
디버깅
- 편집기(F5)에서 실행하면 완전한 디버거 사용 가능: 오류와 스택 추적, 중단점(또는
breakpoint문), 단계 진입/단계 나가기(단계 나가기는 4.6에서 추가됨), Remote 씬 트리(실행 중 라이브 노드 및 속성 검사), 프로파일러, 모니터 및 ObjectDB 스냅샷(4.6). - 로깅:
print,print_rich("[color=yellow]..."),print_debug(파일과 행 추가),push_warning/push_error(스택과 함께 디버거에 표시되며 치명적이지 않음),printerr.assert(cond, "msg")는 디버그 빌드에서만 실행되므로 내부에 부작용을 절대 넣지 마세요. - 파일 로그:
debug/file_logging/enable_file_logging(데스크탑에서 기본적으로 켜짐,user://logs/godot.log).OS.get_user_data_dir()로user://위치를 찾으세요. - 커스텀
Logger(4.5 이상): 서브클래스로_log_error/_log_message를 재정의하고OS.add_logger()로 등록합니다.script_backtraces와 함께 게임 내 버그 리포트에 사용하세요. 릴리스 빌드에서 역추적을 위해debug/settings/gdscript/always_track_call_stacks를 켜세요.Engine.capture_script_backtraces()는 필요 시 역추적을 캡처합니다. - CLI:
-d(stdout 디버거),--verbose,--debug-collisions/--debug-navigation, 그리고--remote-debug tcp://host:6007으로 실행 중인 빌드를 편집기에 연결합니다. - C#: IDE 디버거를 게임 프로세스에 연결(Rider와 VS Code C# Dev Kit은
--path로 Godot을 실행 가능). 예외는 기록될 뿐 치명적이지 않으므로 출력 패널을 주시하세요.
오류 빠르게 읽기
res://file.gd:LINE 형식은 줄 번호를 가리킵니다. "null instance"는 잘못된 노드 경로 또는 _ready 전에 사용된 것을 의미합니다. "previously freed"는 await 또는 콜백이 해당 노드보다 오래 살아남았음을 의미합니다. "Parse Error" 또는 "Compile Error"는 스크립트 로딩을 중단시키므로 이를 사용하는 모든 것이 실패하며, 첫 번째 오류부터 수정해야 합니다. "Condition "!is_inside_tree()" is true"는 트리 API가 아직 트리에 없는 노드에서 호출되었음을 의미합니다. 엔진 C++ 파일 참조(scene/main/node.cpp:123)는 여전히 당신의 호출이 잘못되었음을 의미하므로 스택을 읽으세요.
GdUnit 스위트(단위, 목, 시그널, 씬 러너), C# 테스트, 게임 내 Logger(테스트에 의해 컴파일됨): references/patterns.md