디버깅과 테스트

이전 절에서 우리는 언리얼 엔진에서 게임 시스템을 기획하고 구현하는 방법에 대해 알아보았습니다.

코드를 작성하고 기능을 추가하는 것은 개발의 핵심이지만, 완벽한 코드는 존재하지 않으며 예상치 못한 버그와 문제가 끊임없이 발생합니다.

이때 필요한 것이 바로 디버깅(Debugging)과 테스트(Testing)입니다.

이 두 과정은 게임의 품질을 확보하고 플레이어에게 안정적인 경험을 제공하는 데 필수적입니다.

이번 절에서는 언리얼 엔진 프로젝트에서 효과적인 디버깅 기법과 다양한 테스트 전략을 통해 게임의 버그를 찾아내고 수정하는 방법에 대해 자세히 살펴보겠습니다.

Console
stat fps, show collision 등 즉시 상태 확인
Blueprint Debugger
노드 흐름과 변수 값을 추적
Visual Logger
AI, 이동, 이벤트를 시간축으로 기록
Profiler
CPU, GPU, 메모리 병목 분석
Unit
함수와 클래스 단위 검증
Integration
시스템 간 연동 확인
QA / Playtest
성능, 안정성, 재미 검증

디버깅: 문제의 원인 찾기

이 다이어그램은 버그를 재현하고, 로그와 브레이크포인트로 원인을 좁힌 뒤, 자동화 테스트로 회귀를 막는 흐름을 정리합니다.

단계	해야 할 일	산출물
Repro	입력, 맵, 상태를 최소 조건으로 줄인다	반복 가능한 재현 절차
Trace	로그와 디버거로 값이 어긋나는 지점을 찾는다	의심 함수와 변수 목록
Fix	원인을 고친 뒤 같은 조건에서 다시 실행한다	수정 전후 비교 결과
Test	체크리스트나 자동화 테스트로 회귀를 막는다	다음 빌드에서도 볼 검증 항목

디버깅은 코드의 오류를 식별하고 수정하는 과정입니다.

언리얼 엔진은 강력한 디버깅 도구들을 내장하고 있으며, 외부 IDE와의 연동을 통해 더욱 세밀한 디버깅을 가능하게 합니다.

언리얼 에디터 내 디버깅 도구

인게임 콘솔 (~ 키)
- 가장 빠르고 기본적인 디버그 도구입니다. 게임 실행 중 ~ 키를 눌러 콘솔을 열고 다양한 명령어를 입력하여 게임 상태를 확인하고 변경할 수 있습니다.
- 예시
  - stat fps: 현재 프레임 속도 표시
  - stat unit: CPU 및 GPU 시간 통계 표시
  - show collision: 콜리전 메시 시각화
  - toggledebugcamera: 자유 시점 디버그 카메라 활성화
  - ai.debug [PawnName/ControllerName]: 특정 AI의 디버그 정보 표시
  - log LogTemp Warning: 특정 로그 카테고리의 출력 수준 변경 (실시간)
블루프린트 디버거
- Window -> Developer Tools -> Blueprint Debugger: 블루프린트 로직의 실행 흐름을 시각적으로 추적하고 변수 값을 확인할 수 있습니다.
- 브레이크포인트: 노드에 브레이크포인트를 설정하여 특정 지점에서 실행을 일시 중지하고 단계별로 실행할 수 있습니다.
- 와치(Watch): 특정 변수의 값을 실시간으로 모니터링할 수 있습니다.
비주얼 로거 (Visual Logger)
- Window -> Developer Tools -> Visual Logger: 게임 실행 중 발생하는 이벤트, AI 행동, 이동 경로 등을 시각적으로 기록하고 나중에 재생하여 분석할 수 있습니다. 특히 복잡한 AI나 물리 시뮬레이션 디버깅에 유용합니다.
- 콘솔에서 LogVis 또는 LogVisualizer를 입력하여 활성화합니다.
프로파일러 (Profiler)
- Window -> Developer Tools -> Session Frontend -> Profiler: 게임의 성능 병목 현상을 파악하는 데 사용됩니다. CPU 사용 시간, GPU 시간, 메모리 사용량 등을 상세하게 분석하여 최적화가 필요한 부분을 찾아낼 수 있습니다.
- stat startfile / stat stopfile 명령어를 사용하여 프로파일링 세션을 기록할 수 있습니다.
메모리 스냅샷 (Memory Snapshot)
- Window -> Developer Tools -> Session Frontend -> Memory: 게임의 메모리 사용량을 스냅샷으로 찍어 분석합니다. 메모리 누수나 과도한 메모리 사용량을 찾아내는 데 도움이 됩니다.

외부 IDE (Visual Studio/Xcode) 디버깅

C++ 코드를 사용하는 프로젝트에서 가장 강력한 디버깅 도구입니다.

브레이크포인트: 코드의 특정 줄에 브레이크포인트를 설정하여 프로그램 실행을 일시 중지하고, 해당 지점에서의 모든 정보(변수 값, 호출 스택, 레지스터)를 검사할 수 있습니다.
단계별 실행
- Step Over (F10): 현재 라인을 실행하고 다음 라인으로 이동합니다. 함수 호출 시 함수 내부로 들어가지 않습니다.
- Step Into (F11): 현재 라인을 실행하고, 함수 호출 시 해당 함수 내부로 진입합니다.
- Step Out (Shift+F11): 현재 함수를 모두 실행하고, 해당 함수를 호출한 곳으로 돌아갑니다.
조사식 (Watch) / 지역 (Locals) 창: 변수들의 값을 실시간으로 확인하고 변경할 수 있습니다.
호출 스택 (Call Stack): 현재 코드가 어떤 함수 호출 경로를 통해 실행되었는지 보여주어 버그의 근본 원인을 추적하는 데 매우 중요합니다.
디버그 빌드: Visual Studio 프로젝트 설정을 DebugGame Editor (에디터 내 디버깅) 또는 DebugGame (독립 실행 빌드 디버깅)으로 설정해야 심볼 정보가 포함되어 디버깅이 가능합니다.

로그 시스템 활용

UE_LOG(LogCategory, Verbosity, TEXT("Your message here..."));: C++ 코드에서 특정 카테고리와 중요도(Error, Warning, Log, Verbose 등)를 지정하여 메시지를 출력합니다. 이는 Output Log 창과 로그 파일에 기록됩니다.
Print String 노드: 블루프린트에서 디버그 메시지를 화면에 표시하거나 Output Log에 출력하는 가장 흔한 방법입니다.

디버깅 도구는 증상의 위치가 월드 상태인지, 블루프린트 흐름인지, C++ 호출 경로인지에 따라 먼저 볼 화면이 달라집니다.

Console
월드 상태 이상
Console show collision, toggledebugcamera, Visual Logger로 위치와 상태를 봅니다.
Debugger
블루프린트 분기
Debugger 브레이크포인트와 Watch로 노드 실행 순서와 변수 값을 확인합니다.
IDE
C++ 크래시
IDE DebugGame 빌드에서 호출 스택, 지역 변수, 조사식을 함께 봅니다.
Profiler
성능 저하
Profiler stat unit, Session Frontend, 메모리 스냅샷으로 수치를 분리합니다.
UE_LOG
흔적 부족
UE_LOG 카테고리와 Verbosity를 정해 재현 순간의 근거를 로그로 남깁니다.

테스트: 게임의 품질 보증

테스트는 게임이 의도한 대로 작동하고, 안정적이며, 플레이어에게 즐거운 경험을 제공하는지 확인하는 과정입니다.

개발 중 테스트 (Developer Testing)

유닛 테스트 (Unit Testing)
- 게임의 가장 작은 단위(단일 함수, 특정 클래스)가 올바르게 작동하는지 확인하는 테스트입니다.
- 언리얼 엔진은 Automation Testing Framework를 통해 유닛 테스트를 지원합니다. C++로 작성하며, Test 모듈을 사용하여 테스트 케이스를 정의합니다.
- Engine/Source/Runtime/Core/Public/Tests/ 폴더에 예시가 있습니다.
- AutomationTest.h: IMPLEMENT_SIMPLE_AUTOMATION_TEST 또는 IMPLEMENT_COMPLEX_AUTOMATION_TEST 매크로를 사용하여 테스트를 정의합니다.
- Session Frontend -> Automation 탭: 에디터에서 자동화 테스트를 실행하고 결과를 확인할 수 있습니다.
통합 테스트 (Integration Testing)
- 여러 모듈이나 시스템이 함께 작동할 때 올바르게 연동되는지 확인하는 테스트입니다. (예: 인벤토리 시스템과 UI 시스템이 잘 통합되는지)
엔드 투 엔드 테스트 (End-to-End Testing)
- 게임의 시작부터 끝까지 전체 흐름이 의도한 대로 작동하는지 확인합니다. 실제 플레이어처럼 게임을 진행하며 테스트합니다.
블루프린트 유효성 검사 (Blueprint Validation)
- 에디터 유틸리티 위젯이나 Python 스크립트를 사용하여 블루프린트 에셋의 특정 규칙(변수 명명 규칙, 불필요한 노드 여부 등)을 자동으로 검사합니다.

QA (Quality Assurance) 테스트

개발팀 내부 또는 전문 QA 팀에 의해 수행되는 체계적인 테스트입니다.

기능 테스트 (Functional Testing): 모든 게임 기능이 GDD에 따라 올바르게 작동하는지 확인합니다.
호환성 테스트 (Compatibility Testing): 다양한 하드웨어 구성, 운영 체제, 드라이버 환경에서 게임이 올바르게 작동하는지 확인합니다. (특히 PC 게임)
성능 테스트 (Performance Testing): 목표 프레임 속도, 로딩 시간, 메모리 사용량 등 성능 지표를 측정하고 목표를 달성하는지 확인합니다. (Stress Test, Load Test 포함)
안정성 테스트 (Stability Testing): 장시간 플레이, 반복적인 액션, 극단적인 상황에서도 게임이 충돌하지 않고 안정적으로 작동하는지 확인합니다. (크래시 테스트)
멀티플레이어 테스트: 네트워크 지연, 패킷 손실, 동시 접속자 수 증가 등 다양한 네트워크 환경에서 동기화 및 안정성을 테스트합니다.
사용성 테스트 (Usability Testing): 게임의 UI/UX가 직관적이고 사용하기 편리한지 실제 사용자의 피드백을 통해 검증합니다.
지역화 테스트 (Localization Testing): 게임의 모든 텍스트, 음성 등이 번역된 언어로 올바르게 표시되고 작동하는지 확인합니다.
규정 준수 테스트 (Compliance Testing): 플랫폼별 가이드라인(예: 콘솔 인증, 모바일 스토어 정책)을 준수하는지 확인합니다.

플레이테스트 (Playtesting)

목적: 게임의 재미, 밸런스, 플레이어 경험 등 정성적인 부분을 평가하기 위해 실제 플레이어들에게 게임을 시켜보고 피드백을 수집합니다.
방법: 내부 팀원, 친구, 또는 외부 베타 테스터 그룹을 모집하여 진행합니다.
피드백 수집: 설문조사, 인터뷰, 직접 관찰, 인게임 데이터 로깅 등을 통해 피드백을 수집하고 분석합니다.

버그 트래킹과 관리

버그 트래킹 시스템: Jira, Trello, Asana, MantisBT 등 전용 버그 트래킹 시스템을 사용하여 발견된 모든 버그를 기록하고 관리합니다.
- 필수 정보: 버그 제목, 재현 단계, 예상 결과, 실제 결과, 스크린샷/영상, 발생 빈도, 중요도, 담당자, 상태(새로 생성, 할당됨, 수정됨, 검증됨, 닫힘 등).
재현 가능성: 버그를 정확히 재현할 수 있는 명확한 단계를 작성하는 것이 가장 중요합니다.
우선순위: 버그의 심각도(게임 진행 불가, 크래시)와 발생 빈도에 따라 우선순위를 부여하고 수정 계획을 세웁니다.
회귀 테스트 (Regression Testing): 버그 수정 후, 해당 수정으로 인해 다른 기능에서 새로운 버그가 발생하지 않았는지 확인하는 테스트입니다.

디버깅과 테스트 결과는 버그 리포트, 자동화 테스트, 회귀 확인으로 이어져야 같은 문제가 다시 숨어들 가능성을 낮출 수 있습니다.

Reproduce
빌드·맵·입력 순서와 발생 빈도를 최소 재현으로 고정한다.
Observe
기대/실제 차이와 로그·콜스택을 같은 시간축에 모은다.
Fix Cause
증상을 가리지 않고 실패 계약을 깨뜨린 코드나 데이터를 바꾼다.
Regression
같은 입력이 다시 실패하면 빌드가 알려 주는 검사를 추가한다.
Verify
원래 환경과 주변 기능에서 재현 불가를 확인하고 종료 기록을 남긴다.
재현 증거
절차, 영상, 로그, 빌드 식별자를 함께 남긴다.
수정 근거
어떤 계약이 깨졌고 왜 이 변경이 원인을 제거하는지 적는다.
종료 조건
회귀 검사 통과와 독립 검증을 모두 충족해야 Closed다.

아래 다이어그램은 크래시, 블루프린트, AI, 성능 증상별로 먼저 볼 도구와 수정 후 잠글 테스트를 연결한 품질 기준입니다.

증상 먼저 볼 도구 확인
근거 회귀 잠금
Crash IDE 디버거, 로그 파일
호출 스택, 빌드 구성, 입력 순서 최소 재현 맵 + 자동화 테스트
Blueprint Breakpoint, Watch
변수 변경 시점과 잘못된 분기 블루프린트 QA 체크리스트
AI Debugger, Visual
Logger 트리 노드, 블랙보드, 이동 경로 행동 시나리오 통합 테스트
Performance stat unit
Profiler CPU, GPU, 메모리 병목 위치 프레임 예산 기준선 비교

디버깅과 테스트는 게임 개발 과정에서 끊임없이 반복되어야 하는 필수적인 활동입니다.

언리얼 엔진이 제공하는 강력한 내장 디버깅 도구와 외부 IDE의 기능을 적극적으로 활용하여 코드 레벨의 문제를 해결하고, 유닛 테스트부터 QA 테스트, 그리고 플레이테스트에 이르기까지 다양한 테스트 전략을 통해 게임의 기능, 성능, 안정성, 그리고 재미를 검증해야 합니다.

효과적인 버그 트래킹과 관리는 팀의 생산성을 높이고, 궁극적으로 플레이어에게 고품질의 게임을 제공하는 데 기여할 것입니다.

증상을 재현하고 도구로 좁힌 뒤 테스트로 잠그는 순서를 한 장으로 정리합니다.

Case
맵, 빌드, 입력 순서, 기대와 실제 결과를 고정한다.
Trace
현상에 맞는 에디터·디버거·로그·프로파일러 증거를 붙인다.
Regression
수정 전 실패하고 수정 후 통과하는 재검사 기준을 만든다.
Close
원인, 수정 위치, 확인 빌드, 남은 위험을 종료 기록에 남긴다.

디버깅과 테스트에서는 재현 조건, 로그 카테고리, 브레이크포인트 위치, 자동화 테스트 범위를 함께 점검합니다.

이 페이지의 목차