live-app-translator/docs/WINDOWS-TESTING.md

Windows에서 자동 검증 붙이기

개발은 리눅스에서 하고 있어서 Windows 전용 경로는 테스트가 불가능합니다. 오디오 캡처, 전역 단축키, 모니터 열거, exe 빌드가 전부 여기에 해당합니다. 그래서 "리눅스에서 다 통과했는데 윈도우에서 안 되더라"가 나올 수 있습니다.

Windows 러너를 하나 붙이면 main 에 push할 때(또는 Actions 탭에서 수동 실행할 때) 이 경로들이 자동으로 검증됩니다.

어디에 올릴까 — 서버 Windows VM 권장

개인 PC를 안 쓰고 서버에 올려 완전 자동화하는 게 가장 깔끔합니다. GPU가 없어도 됩니다. 실제로 확인해봤습니다.

검증 항목	GPU 필요?	GPU 없는 서버 VM
단위 테스트 189개	❌	✅
WASAPI 장치·프로그램 열거	❌	✅
전역 단축키	❌	✅
모니터 열거·자막 배치	❌	✅
포터블 exe 빌드·기동	❌	✅
오디오 → 한국어 자막 (전 과정)	❌ CPU로 됨	✅
CUDA 인식·VRAM 상한	✅	⚠️ 경고만 (빌드 통과)

GPU가 필요한 건 마지막 한 줄뿐이고, 그건 이 서버(.9, 리눅스)에 RTX 5050이 물려 있어 이미 거기서 검증하고 있습니다. GPU는 한 VM만 독점할 수 있으니 Windows VM에는 안 주는 게 맞습니다.

Proxmox에 Windows VM 만들기

# Proxmox 호스트에서 (VMID 는 비어 있는 번호로)
qm create 920 --name win-ci --memory 8192 --cores 4   --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-single   --scsi0 local-lvm:80 --ostype win11 --machine q35 --bios ovmf   --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1 --tpmstate0 local-lvm:1,version=v2.0   --ide2 local:iso/Win11.iso,media=cdrom --ide0 local:iso/virtio-win.iso,media=cdrom   --audio0 device=ich9-intel-hda,driver=none   --vga std

RAM 8GB / 디스크 80GB면 충분합니다(모델 캐시 포함). 아래 둘을 꼭 넣으세요.

• --audio0 ... — 없으면 오디오 장치가 하나도 안 잡혀 WASAPI 점검이 실패합니다
• --vga std — 화면이 있어야 자막 오버레이를 그리고 스크린샷을 찍습니다

VM 안에서 꼭 해야 하는 두 가지

1. 자동 로그온 — 러너가 서비스로 돌면 데스크톱 세션이 없어 GUI 테스트와 스크린샷이 전부 실패합니다. 자동 로그온 + 로그온 시 실행이어야 합니다.

# 관리자 PowerShell (VM 안이므로 부담 적음)
$k = "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon"
Set-ItemProperty $k AutoAdminLogon 1
Set-ItemProperty $k DefaultUserName "ci"
Set-ItemProperty $k DefaultPassword "<비밀번호>"

2. 화면 꺼짐·잠금 끄기 — 잠기면 GUI 테스트가 실패합니다.

powercfg /change monitor-timeout-ac 0
powercfg /change standby-timeout-ac 0

그 다음은 아래 일반 설치 절차와 같습니다. 러너는 서비스가 아니라 로그온 예약 작업으로 등록하세요(아래 "항상 켜두고 싶다면" 참고).

---

무엇이 자동으로 확인되나

항목	리눅스에서	Windows 러너에서
단위 테스트 189개	✅	✅
WASAPI 루프백 장치 열거	❌	✅
소리 내는 프로그램 열거	❌	✅
전역 단축키 등록/해제	❌	✅
모니터 열거·자막 배치	가상 화면만	✅ 실제 모니터
포터블 exe 빌드	❌	✅
exe가 실제로 뜨는지	❌	✅
GPU 인식 (CUDA)	이 서버 GPU	✅ 실제 게임 PC GPU
실제 화면 스크린샷	offscreen	✅ 진짜 화면

결과물(exe, 스크린샷, 로그)은 Gitea Actions의 artifact로 올라오므로 원격에서도 눈으로 확인할 수 있습니다.

---

설치 (약 10분, 한 번만)

1. 필요한 것 설치

winget install Git.Git                                  # 소스 받기 (checkout) 에 필요
winget install Microsoft.PowerShell                     # 워크플로가 pwsh 7 을 씁니다
winget install Python.Python.3.12
winget install Kitware.CMake
winget install Microsoft.VisualStudio.2022.BuildTools   # C++ 데스크톱 워크로드 선택

Git.Git 과 Microsoft.PowerShell 은 빠뜨리기 쉬운데 둘 다 필수입니다. Git 이 없으면 소스를 못 받고, Windows 에 기본으로 깔린 PowerShell 은 5.1 이라 워크플로가 쓰는 pwsh(7.x) 가 없으면 단계마다 실패합니다. 설치 후 새 PowerShell 창을 열어 git --version, pwsh --version 이 나오는지 확인하세요.

2. Gitea 러너 내려받기

https://gitea.com/gitea/act_runner/releases 에서 act_runner-<버전>-windows-amd64.exe 를 받아 C:\gitea-runner\act_runner.exe 로 둡니다.

3. 등록 토큰 받기

Gitea 웹에서 저장소 → 설정 → Actions → 러너 → 등록 토큰 생성 (주소: https://git.tkrmagid.kr/tkrmagid/live-app-translator/settings/actions/runners)

4. 등록하고 실행

cd C:\gitea-runner
.\act_runner.exe register --no-interactive `
  --instance https://git.tkrmagid.kr `
  --token <위에서 받은 토큰> `
  --name windows-test `
  --labels windows:host

.\act_runner.exe daemon

--labels windows:host 가 중요합니다. 워크플로의 runs-on: windows 와 이름이 맞아야 하고, :host 는 컨테이너가 아니라 그 PC에서 직접 돌리라는 뜻입니다 (생략해도 기본값이 host 지만 명시하는 편이 낫습니다).

이름이 안 맞으면 Gitea 는 작업을 실패시키지 않고 기본 우분투 컨테이너에서 돌립니다. Windows 검증이 조용히 리눅스에서 돌아가는 셈이라, 워크플로 첫 단계에서 그걸 막아 뒀습니다.

5. 확인

워크플로는 main 에 push될 때 또는 Actions 탭에서 수동 실행할 때 돕니다. (.gitea/workflows/windows.yml 의 on: 항목)

저장소 Actions 탭 → Windows → Run workflow 로 바로 한 번 돌려보세요.

---

항상 켜두고 싶다면 (선택)

서비스(sc.exe create)로 등록하지 마세요. 그렇게 하면 SYSTEM 권한으로 돌아가 러너가 PC 전체를 건드릴 수 있게 됩니다. 로그인할 때 그 계정 권한으로 뜨게 하는 편이 안전합니다.

# 관리자 아님 — 그냥 평소 PowerShell
$action  = New-ScheduledTaskAction -Execute "C:\gitea-runner\act_runner.exe" `
                                   -Argument "daemon" -WorkingDirectory "C:\gitea-runner"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "gitea-runner" -Action $action -Trigger $trigger

게임할 때 방해되면 그냥 꺼두고, 확인이 필요할 때만 daemon 을 켜도 됩니다. 러너가 꺼져 있으면 워크플로는 대기만 하고 아무 일도 하지 않습니다.

---

안전에 대해 — 정확히 어떤 권한인가

솔직하게 말하면, 이건 "그 PC에서 명령을 실행할 수 있는 권한"입니다.

러너는 저장소의 워크플로 파일을 실행합니다. 그런데 저(Claude)는 이 저장소의 main에 push할 수 있으므로, 워크플로 파일을 고쳐서 커밋하면 결과적으로 그 PC에서 원하는 명령을 돌릴 수 있습니다. "커밋된 파일만 실행하니 안전하다"는 말은 정확하지 않습니다.

실제로 보장되는 것은 이것뿐입니다.

• 숨길 수 없습니다. 실행되는 모든 것은 .gitea/workflows/ 안에 있고 git 기록에 남습니다. 몰래 뭘 했는지 나중에 전부 확인할 수 있습니다.
• 러너를 끄면 즉시 멈춥니다. daemon 을 종료하면 그만입니다.
• 러너는 자기 계정 권한으로 돕니다. 관리자로 띄우지 마세요.

그래서 권하는 방식은 이렇습니다.

방법	위험	얻는 것
Windows VM (Proxmox 등)	거의 없음	빌드·단축키·모니터·UI·exe 실행
전용 Windows 계정	낮음 — 그 계정 파일만 노출	위 전부 + 실제 GPU
평소 쓰는 계정	개인 파일·브라우저 세션 노출	위 전부 + 실제 게임 소리

VM이나 전용 계정을 권합니다. GPU와 실제 게임 소리 확인은 못 하지만, 지금 미검증인 항목의 대부분(빌드·단축키·모니터·UI·exe 기동)은 거기서도 그대로 검증됩니다. GPU/오디오는 필요할 때만 평소 계정에서 한 번씩 확인하는 편이 낫습니다.

부담스러우면 러너를 붙이지 않고 아래 "러너 없이 직접 돌려보기"만 하셔도 충분합니다.

---

러너 없이 직접 돌려보기

러너를 안 붙이고 그때그때 확인만 하고 싶다면 이것만 실행하고 결과를 보내주셔도 됩니다.

git clone https://git.tkrmagid.kr/tkrmagid/live-app-translator
cd live-app-translator
py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install -r packaging\requirements-portable.txt pytest
$env:PYTHONPATH="src"
.\.venv\Scripts\python -m pytest tests -q
.\.venv\Scripts\python packaging\windows_smoke.py

artifacts\windows-smoke.txt 와 artifacts\*.png 를 보내주시면 됩니다.