Harness 운영 가이드

요구사항 접수부터 Step 실행, TDD 정책, MSVC 빌드·테스트, 재시도와 커밋까지의 전체 흐름은 Harness Framework 동작 과정을 참고한다.

Requirements

Windows, Python 3.10 이상, Codex CLI가 필요하다. CMake 프로젝트에는 Visual Studio의 Desktop development with C++ 워크로드와 MSBuild, CMake/CTest를 설치한다.

프로젝트 자동 감지

프로젝트 형식은 다음 순서로 결정한다: .harness/config.json의 명시적 type, 루트의 CMake metadata, 하나의 .sln, 하나의 .vcxproj 순서다. C/C++가 아닌 저장소는 건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는 오류로 처리한다.

설정을 시작하려면 다음을 실행한다.

Copy-Item .harness/config.example.json .harness/config.json
python scripts/execute.py <phase-name>
python scripts/execute.py <phase-name> --push

Harness Python 검증

이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고 다음 명령으로 실행한다.

uv run --with pytest python -m pytest -v -rs

CMake preset 설정

projectType을 cmake로 지정하거나 자동 감지를 사용한다. cmake.sourceDir, binaryDir, configurePreset, buildPreset, testPreset은 preset을 사용할 때 함께 지정해야 한다. 빌드 산출물은 저장소의 .harness/build/처럼 격리된 경로에 둔다.

{
  "version": 1,
  "projectType": "cmake",
  "cmake": {
    "sourceDir": ".",
    "binaryDir": "out/build/windows-debug",
    "configurePreset": "windows-debug",
    "buildPreset": "windows-debug",
    "testPreset": "windows-debug"
  }
}

cmake --preset windows-debug
cmake --build --preset windows-debug
ctest --preset windows-debug --output-on-failure

Preset을 쓰지 않는 경우에는 같은 격리된 build directory를 명시한다.

cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --output-on-failure

직접 MSBuild 설정

projectType을 msbuild로 설정하면 msbuild.solution, configuration, platform을 지정한다. 직접 MSBuild 프로젝트에서는 msbuild.testCommand가 필수이며, 테스트 실행 파일과 인수를 JSON 배열로 적는다.

{
  "version": 1,
  "projectType": "msbuild",
  "msbuild": {
    "solution": "MyProject.sln",
    "configuration": "Debug",
    "platform": "x64",
    "testCommand": ["build/tests/Debug/MyProjectTests.exe"]
  }
}

MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
.\build\tests\Debug\MyProjectTests.exe

TDD 확장

tdd.testRoots와 tdd.testPatterns로 테스트 위치와 이름을 확장한다. 패턴마다 {stem}이 필요하다. main, 테스트, 외부 의존성, 생성 파일, build directory 같은 기본 제외 항목은 Harness가 관리하며, tdd.exclude의 사용자 제외 항목은 이를 대체하지 않고 추가한다.

{
  "version": 1,
  "tdd": {
    "testRoots": ["tests", "integration-tests"],
    "testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
    "exclude": ["legacy/generated/**"]
  }
}

실패 복구

Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다.
solution 또는 project가 여러 개라서 모호하면 projectType과 msbuild.solution을 명시한다.
MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다.
CTest가 0개 테스트를 보고하면 enable_testing()과 테스트 등록을 확인한다.
직접 MSBuild 구성에 test command가 없으면 msbuild.testCommand 배열을 추가한다.
timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리, 종료 코드와 출력 tail을 확인하고 해당 명령을 단독으로 다시 실행한다. Harness는 별도의 로그 파일을 만들지 않는다.

4.1 KiB Raw Blame History