Community코딩 & 개발github.com

godot-testing-debug

Godot 4.7 프로젝트를 테스트하고 디버그합니다 - GdUnit4(GDScript)와 gdUnit4Net(C#)의 검증된 버전, 단위/씬 러너 테스트, 목(mock), 시그널 단언, 입력 시뮬레이션, 헤드리스 실행(JSON), 디버거, 중단점, 커스텀 Logger, 역추적, 오류 읽기 등을 지원합니다. 테스트 작성, 실행, 버그 및 충돌 추적 시 사용하세요.

godot-testing-debug란 무엇인가요?

이 스킬은 Godot 4.7 프로젝트에서 테스트와 디버깅을 수행하는 방법을 설명합니다. GdUnit4(GDScript)와 gdUnit4Net(C#) 라이브러리를 사용하여 단위 테스트, 씬 러너 테스트, 목(mock), 시그널 단언, 입력 시뮬레이션을 지원하며, 헤드리스 모드로 실행하여 JSON 형식의 결과를 얻을 수 있습니다. 스킬은 `python scripts/test_run.py` 명령어를 통해 테스트를 자동화하고, JUnit/콘솔 결과를 파싱하여 성공/실패 정보를 반환합니다. 또한 편집기 내 디버거(F5), 커스텀 Logger, CLI 디버그 플래그, C# IDE 디버거 연결 등 다양한 디버깅 도구를 제공하며, 오류 메시지를 빠르게 해석하는 방법까지 다룹니다. 버그 수정 시 회귀 테스트를 추가하는 것이 권장됩니다.

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

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

테스트 및 디버깅 (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.Sdk 18.x, gdUnit4.api 5.1.0-rc5 (어댑터 3.1.1은 ≥5.1.0-rc5 필요; 5.0.0은 NU1605로 복원 실패), gdUnit4.test.adapter 3.1.1, gdUnit4.analyzers 1.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

Individual skills in this repo

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

관련 스킬