테스트 요구 사항

모든 동작 변경에는 정확성을 입증하고 디버깅 가능성을 유지하는 테스트가 포함되어야 합니다.

기본 기대 사항

대부분의 기능 작업의 경우 다음을 포함하는 테스트를 추가하거나 업데이트합니다.

• 파이프라인 빌드 정확성(예상되는 조각/문자열 형식).
• 파싱/검증 동작(캡스 협상 및 검증 실패).
• 런타임 동작(run, 적용 가능한 경우 푸시/풀 및 종료 경로).
• 진단 품질(PipelineReport가 실패 경로에서 얼마나 유용한지).

변경 유형별 필수 테스트 유형

새 노드 또는 노드 그룹

• 결정적 조각 생성을 위한 단위 수준 검사.
• 캡스 또는 연결 가정에 대한 검증/파싱 적용 범위.
• 노드가 실제 체인에서 작동하는지 입증하는 최소 하나의 통합 경로.

런타임/파이프라인 오케스트레이션 변경

• 예상되는 출력 동작에 대한 성공 경로 테스트.
• 시간 초과, 플러그인 부재 또는 유효하지 않은 그래프 조건에 대한 실패 경로 테스트.
• 상태 처리가 변경될 때의 종료/수명 주기 안전성 어설션.

공개 API 시그니처 변경

• 변경된 공개 헤더/사용법을 사용하는 컴파일 타임 적용 범위를 추가하거나 업데이트합니다.
• 비호환성 확장이 아닌 경우 기존 사용법이 여전히 컴파일되는지 확인합니다.
• 승인된 호환성이 깨지는 변경 사항의 경우 대체 API 경로를 검증하는 마이그레이션 중심 테스트/예제를 포함합니다.

Python 바인딩 변경(python/, pyneat)

• python/tests 내에서 pytest 적용 범위를 추가/업데이트합니다.
• 상호 운용 계약(NumPy/PyTorch DLPack 경로, 복사 대 제로 복사 동작)을 포함합니다.
• 설치된 휠 또는 편집 가능한 설치에 대한 최소 하나의 가져오기/스모크 테스트를 추가합니다.

진단 또는 관측 가능성 변경

• 추가/변경된 보고서 필드에 대한 테스트.
• 스트리밍 스레드에서 데이터가 업데이트될 때의 동시성 안전 동작.

회귀 및 결정성 정책

• 버그 수정에는 회귀 테스트가 포함되어야 합니다.
• 결정적 명명 및 안정적인 파이프라인 생성을 확인하는 테스트를 선호합니다.
• 출력이 의도적으로 비결정적인 경우 그 이유를 문서화하고 어설션을 안정적인 불변량으로 제한합니다.

처리량 테스트의 CPU 비용

async_yolov8_tput_test는 완료 프레임당 프로세스 전체의 사용자, 시스템 및 총 CPU 마이크로초와 average_busy_cores를 보고합니다. 후자는 CPU 시간을 실제 경과 시간으로 나눈 값이며, 보드 전체의 백분율이나 가속기 사용률이 아닙니다. 여러 CPU 스레드가 동시에 작업하면 1을 넘을 수 있습니다.

cpu_window_fps는 CPU 카운터와 동일한 구간을 사용합니다. 측정 대상 첫 제출 전부터 최종 출력 해제까지입니다. 워밍업, 결과 검증, 보고 및 정리는 제외합니다. 기존 avg_fps 구간과 처리량 기준은 변경하지 않습니다. output_extraction_included와 output_validation은 테스트가 수행한 작업을 나타냅니다. 동등한 설정을 비교하세요. 미완료 실행이나 수치 검증 실패 실행은 CPU/프레임 값 없이 cpu_window_complete=0을 보고합니다. 처리량 기준을 만족하지 못해도 프레임이 정상적으로 완료되었다면 측정값은 그대로 보고합니다.

새 벤치마크는 실행당 프로세스 전체 스냅샷 두 개를 얻는 tests/perf/process_cpu_metrics.h를 재사용할 수 있습니다. CPU/프레임 계산만을 위해 프레임마다 CPU 카운터를 샘플링하거나 모니터링 스레드를 추가하지 마세요.

건너뛰기 정책

• 건너뛰기 경로를 일반적인 제어 흐름이 아닌 예외로 처리합니다.
• 엄격한 테스트(기본값)는 런타임/도구/픽스처가 누락되어 실행할 수 없는 경우 실패해야 합니다.
• 명시적으로 long으로 표시된 테스트만 건너뛰기 의미(return 77)를 사용할 수 있으며, 해당 테스트는 주간 실행 주기에서 실행됩니다.
• 새로운 테스트 추가 시 엄격한 경로에 skip_test(...)를 도입해서는 안 됩니다.

실용적인 명령

프로젝트 빌드 진입점을 사용합니다.

./build.sh --all

문서에 영향을 미치는 변경 사항의 경우, 다음 명령어도 실행하세요.

./build.sh --doc

지원되는 모든 빌드/테스트 모드는 구축하다를 참조하십시오.

기여자 확인 목록

PR을 열거나 병합하기 전에 다음 사항을 확인하십시오.

• 추가/업데이트된 테스트가 변경된 동작과 일치하는지 확인합니다.
• 기존 관련 테스트가 여전히 통과하는지 확인합니다.
• 사용자에게 보이는 동작에 맞게 문서를 업데이트합니다.
• API/아키텍처 변경 사항이 아키텍처에 반영되었는지 확인합니다.
• 공개 API 변경 사항이 코딩 표준의 API 호환성 정책을 준수하는지 확인합니다.

필수 적용 범위 및 기능 프로파일

정식 CTest 레인은 실행 전에 정확한 선택 목록을 기록하고 새로운 JUnit 결과와 비교합니다. 빈 선택, 누락 또는 중복 결과, 건너뛰기, 비활성화된 테스트 및 실행 실패는 필수 적용 범위 실패로 처리합니다. 테스트 선택자, 인수 및 제한 시간은 집계 도구가 아니라 레인이 계속 소유합니다.

long이 아닌 등록은 SKIP_RETURN_CODE, 건너뛰기 정규식 또는 long 전용 환경으로 검사를 피할 수 없습니다. 필수 레인은 기존 long 테스트를 정식 return-77 등록으로 선택할 수도 있지만 실제 건너뛰기는 여전히 실패입니다. Fast는 long 레이블의 스트레스 테스트를 유지하며 조용히 선택에서 제외하지 않습니다. 소스의 건너뛰기 참조 수는 참고 정보이지 건너뛴 테스트 수가 아닙니다.

cmake/NeatGuardedTests.cmake는 SIMANEAT_GUARDED_HARDWARE_TESTS=ON일 때 기존 하드웨어 감독자를 통해 테스트와 튜토리얼을 등록합니다. 이것이 하드웨어 실행 허가를 생성하지는 않습니다. 감독자 기반 검증은 명시적으로 선택하는 모드이며 표준 CI는 감독자 소켓 없이 직접 실행합니다. 감독자를 사용하는 네이티브 레인을 실행하기 전에 구성된 장치 소유권과 허가를 확보하세요. 결과 검증기는 등록 정책을 확인하며, 감독자를 대체하거나 하드웨어 실행을 승인하지 않습니다.

Python 레인은 선택한 노드 ID와 명시적으로 제외한 노드 ID를 기록합니다. 필수 설정, 호출 및 정리 결과가 모두 통과해야 합니다. 선택 전에 선택적 적용 범위를 구성합니다.

프로파일	구성	요구사항
Python 런타임	NEAT_CI_PYTHON_PROFILE=runtime (기본값)	준비된 ResNet 픽스처로 Graph Phase 3을 활성화하며 Torch는 명시적으로 제외합니다.
Torch 통합	NEAT_CI_PYTHON_PROFILE=torch	검토된 정확한 NEAT_CI_TORCH_VERSION을 설정합니다. 설치/가져오기에 성공해야 합니다.
MIPI 카메라	SIMA_NEAT_TEST_MIPI_CAMERA=1	카메라 하드웨어, SIMA_NEAT_TUTORIAL_MODEL_MIPI 및 SIMA_NEAT_TUTORIAL_MIPI_DECODE를 제공합니다.
주간 HTTP 스트림	NEAT_CI_STREAM_PROFILE=http (기본값)	HTTP MJPEG URL과 양의 FPS를 제공합니다. 두 HTTP 사례와 동기 스모크 검사는 계속 필수입니다.
주간 HTTP + RTSP 스트림	NEAT_CI_STREAM_PROFILE=all	H264, H265 및 MJPEG RTSP URL과 양의 MJPEG FPS도 제공합니다.

하드웨어가 필요 없는 카메라 API 테스트는 항상 런타임 프로파일에 포함됩니다. 카메라와 Torch 제외는 통과가 아니라 적용 범위 공백으로 남습니다. 스트림 프로파일은 codec_stream 사례 등록을 다루며, 다른 제외된 RTSP 레인을 검증하지 않습니다. 각 스트림 사례에는 별도의 스모크 및 반복 계약 결과가 있으므로, 사용 가능한 HTTP 스트림으로 실행하지 않은 RTSP 사례를 종합 PASS 안에 숨길 수 없습니다.

주간 모델 준비에는 SIMA_CI_MNIST_MODEL, SIMA_CI_SSD300_MODEL, SIMA_CI_MNIST_IMAGES 및 SIMA_CI_MNIST_LABELS 각각의 로컬 경로 또는 HTTPS 위치와 검토된 SHA-256을 설정합니다. 각 체크섬은 일치하는 _SHA256 변수를 사용합니다. 데이터셋 입력은 압축된 MNIST IDX 테스트 파일입니다. 준비 과정은 정확한 바이트를 확인하고 기존 테스트의 캐시/변수를 스테이징합니다. 누락되거나 일치하지 않는 입력은 준비 실패입니다. 관련 없는 기존 캐시를 수정하지 않습니다. 모델 준비는 RTSP 가용성에 의존하지 않습니다.

선택, 결과 및 프로파일 제외 보고서를 레인 결과와 함께 보관합니다. 선택한 프로파일의 통과는 모든 선택적 하드웨어 또는 통합 프로파일이 통과했다는 뜻이 아닙니다.

로컬 주간 준비

CI뿐 아니라 로컬 실행에서도 tools/ci/prepare_weekly_fixtures.py를 사용합니다. 기본적으로 준비에는 mnist와 ssd300이 모두 필요합니다. MNIST만 검증하려면 --fixture-group mnist를 명시적으로 전달합니다. 보고서는 SSD300을 미검증으로 표시합니다. 이 선택은 CTest 선택을 바꾸거나 건너뛴 필수 사례를 통과로 만들지 않습니다. 전체 주간 검증에는 여전히 두 그룹 모두 필요합니다.

로컬 실행기에는 --environment-json <file>, GitHub Actions에는 --github-env <file>을 사용하거나 둘 다 사용합니다. 두 출력은 동일한 환경 매핑을 담습니다. 로컬 실행기는 선택을 기록하거나 하드웨어 프로세스 실행을 허가하기 전에 JSON 매핑을 테스트 프로세스 환경에 병합해야 합니다. JSON은 셸 스크립트도 테스트 결과도 아닙니다. 파일을 생성하기만 해서는 변수가 내보내지지 않습니다.

헬퍼는 선택한 모델과 MNIST gzip/IDX 파일이 검증된 후에만 SIMA_RUN_MNIST_PREPROC_CHANNELS1=1을 내보냅니다. gzip CRC, IDX 지오메트리, 길이, 이미지/레이블 개수 및 레이블 범위를 검사하며, 충돌하는 압축 또는 원시 캐시 항목을 거부합니다. 준비 시도마다 새 출력 디렉터리를 사용합니다. 실패한 스테이징 바이트는 진단할 수 있도록 남겨 둡니다.

설치된 패키지와 비공개 접두사 통합

다음 검증 범위를 구분합니다.

• 비공개 접두사 통합은 전역 패키지 데이터베이스를 수정하지 않고 선택한 헤더, 라이브러리 및 플러그인을 확인합니다. Debian 설치를 검증하는 것은 아닙니다.
• 설치된 패키지 검증은 실제 DevKit 루트 파일시스템, dpkg 기록, 페이로드 바이트, 심볼릭 링크 및 파일 소유권을 선택한 검증된 아카이브와 대조합니다. 비공개 접두사는 이 검사를 충족할 수 없습니다.

계속 scripts/ci/verify_core_dist.sh로 배포 구성을 검증합니다. 로컬 빌드에서는 독립적으로 선택한 --expected-manifest, --expected-receipt 및 --expected-deb-dir 입력도 포함합니다. 다섯 메타데이터 변형이 포함된 완전한 생성기 배포본을 사용합니다. 원격 sima-cli 설치는 선택된 리소스를 스테이징하지만 해당 메타데이터 파일은 보존하지 않습니다. CI 워크플로는 이 실행의 완전한 neat-core-dist 아티팩트를 별도로 다운로드한 다음 실제 CLI 설치 패키지를 이 독립 입력과 비교합니다. 설치된 머신에서 생성기 메타데이터를 다시 만들지 마세요.

필수 패키지 프로파일을 명시적으로 선택합니다.

프로파일	필수 역할
core	Core 런타임/개발, Kernels 개발, Runner, Scheduler 및 런타임 호환성 패키지
core-codecs	core 및 Codecs 런타임/개발 쌍
core-codecs-llima	core-codecs 및 LLiMa 런타임/CLI 쌍

소비된 선택적 백엔드 제공자는 선택한 생성기 영수증에 따라 계속 필수입니다. 누락된 아카이브로 프로파일을 추론하지 않습니다. LLiMa와 폐기된 메모리 구현은 Core 전용 테스트의 무조건적인 의존성이 아닙니다.

DevKit에서 기존 설치 프로그램을 사용하기 전에 tools/ci/verify_core_dist.py의 --capture-platform-baseline <file>로 기준선을 캡처합니다. 설치 후 배포 검증기를 --package-profile <profile>, --verify-installed, --platform-baseline <file> 및 --write-package-inventory <file>로 실행합니다. 기준선은 추적 대상 네이티브 패키지의 설치 또는 부재 상태를 기록합니다. 해당 상태와 관련 없는 네이티브 패키지 버전, OTA 명령의 가용성을 보존합니다. OTA 명령이 있으면 정식 경로, 소유권 및 바이트가 변하지 않아야 합니다. 과거 패키지 이름과 OTA 명령이 모든 이미지에 있어야 하는 것은 아니지만 Palette는 여전히 필수입니다. 검증된 배포본에 명시적으로 포함된 제공자는 업그레이드할 수 있으며, 대신 선택된 아카이브와 대조합니다.

절대 인벤토리 경로를 SIMA_TEST_PACKAGE_INVENTORY로, 설치 전 기준선 경로를 SIMA_TEST_PLATFORM_BASELINE으로 기존 devkit-package-inventory CTest 레인에 전달합니다. 설치 후 기준선을 다시 캡처하지 마세요. 선택된 인벤토리는 예상 아카이브 데이터를 담으며 설치 PASS가 아닙니다. 네이티브 테스트는 실제 패키지 버전/아키텍처, 로드된 Core/라이브러리 경로 및 소유권, 선택되지 않은 네이티브 패키지의 변하지 않은 존재/부재, 폐기된 패키지의 부재, OTA 가용성 및 식별 정보를 독립적으로 확인합니다. 설치된 헤더 예제는 계속 별도로 컴파일합니다. 패키지가 있다는 사실은 소비자가 컴파일되거나 백엔드가 올바르게 실행되었다는 증거가 아닙니다.

네이티브 빌드 도구 전제 조건

Ubuntu에서 .github/workflows/vulcan-ci.yml의 빌드 도구 pytest 선택을 실행하기 전에 build-essential, file, nlohmann-json3-dev 및 python3-venv를 설치합니다. 플랫폼 기준선 프로브는 실제 공유 C++ 계약을 -Werror로 컴파일합니다. 컴파일러/헤더 누락은 건너뛴 검사가 아니라 테스트 설정 실패입니다. 실패 시 컴파일러 stdout/stderr가 포함되며, file로 네이티브 실행 파일을 확인한 뒤 실행합니다.