Hand test (수동 테스트)
테스트는 코드가 무엇을 하는지 증명합니다. 수동 테스트(hand test) 는 사람이 의도한 것을 제대로 받았는지 증명합니다. 사람이 보고, 듣거나 느낄 수 있는 각 변경 사항에 대해 낯선 사람이 1분 안에 판단할 수 있는 증거를 만듭니다(차갑게: 하나의 비디오와 하나의 보드, BEFORE(빨간색 배지)와 AFTER(초록색 배지)를 같은 장소, 같은 동작으로 나란히 배치하여 오직 한 가지 변경 사항만 다르게 합니다). 변경 사항은 승인자가 OK라고 말할 때까지 병합되지 않은 상태로 유지됩니다.
프로젝트 정보는 사용자 저장소의 docs/agents/hand-test.md에 있습니다: BEFORE를 얻는 방법, 이 표면을 구동하고 캡처하는 방법, 장치 규칙, 증거가 저장되는 위치, 승인자, OK와 Not OK의 역할 등이 명시됩니다. 해당 파일이 없으면 먼저 SETUP.md를 따르십시오.
도구는 scripts/handtest.py입니다. uv run <이 스킬의 폴더>/scripts/handtest.py <명령어>로 실행하며, --help는 각 명령어의 플래그를 나열합니다. ffmpeg와 ffprobe가 PATH에 있어야 하고, uv는 Pillow를 함께 가져옵니다. uv가 없으면 저장소 외부에 가상 환경을 만들고(python3 -m venv <dir> && <dir>/bin/pip install pillow), <dir>/bin/python으로 도구를 실행합니다.
1. 변경 사항 분류
PR 본문(또는 변경 사항이 설명된 곳)에 ## Hand test 섹션을 추가합니다:
yes: <찾아야 할 것>: 사람이 보고, 듣거나 느끼는 모든 것 (UI, 동작, 타이밍, 소리, 카피, 디자인)no: <보이거나 들리거나 느껴지지 않는 이유>: 도구, 빌드, 테스트, 문서, 또는 동일한 출력의 리팩터
의심스러우면 yes입니다.
완료 조건: 섹션이 추가됨. no이면 스킬이 종료됩니다.
2. 촬영 계획 수립
순간(the moment) 을 지정합니다: 변경 사항이 드러나는 한 단계. 변경 사항이 첫 프레임부터 화면에 나타나는 경우(색상, 레이블, 레이아웃), 순간은 화면이 도착하는 순간 또는 그 이후 첫 단계입니다.
실제 앱을 구동하는 스크립트를 작성합니다. 양쪽 모두 동일해야 합니다(표면별 명령어는 CAPTURE.md 참조):
- 앱 자체 UI를 통한 실제 입력: 테스트 단축키는 사람이 직접 접촉하는 코드를 건너뜁니다.
- 요소는 레이블이나 역할로 찾고, 좌표로 절대 찾지 마십시오: 레이아웃 이동이 종종 변경 사항 자체입니다.
- 순간 이전에는 실제 상태(레이블 표시, 요청 완료)를 기다리고 고정 타이머를 사용하지 마십시오. 순간 이후에는 고정 시간을 유지합니다.
- 양쪽 모두 동일한 장치, 창 크기, 언어, 데이터 및 시작 상태를 사용합니다.
finally블록에서 모든 것을 원래대로 되돌립니다.
BEFORE는 실제 이전 상태에서 가져옵니다: 베이스 커밋의 빌드, 또는 런타임에 변경 사항을 끈 상태. BEFORE를 위해 저장된 파일 변경 사항은 없어야 합니다.
변경 사항이 빌드 전에 아무도 정하지 않은 공간, 시간 또는 느낌에 관한 질문이라면(얼마나 크게, 얼마나 빠르게, 어떻게 느껴져야 하는지), 중단하고 사용자에게 알립니다. 그런 것은 빌드 전 인터랙티브 스케치에서 다뤄야 합니다; 수동 테스트는 결정을 확인하는 것이지 결정을 내리는 것이 아닙니다.
완료 조건: 스크립트가 BEFORE와 AFTER에서 녹화 없이 건조 실행되고, 모든 요소를 찾거나(또는 모든 상태에 도달하며, 정지만 촬영 가능한 경우) 장치와 작업 트리를 원래대로 두고 트리의 체크섬이 전후 같습니다.
3. 양쪽 녹화
BEFORE, 그 다음 AFTER를 동일한 스크립트로 녹화합니다. 프로젝트의 장치 규칙을 따릅니다: 테스트 중인 앱만 터치하고, 아무것도 제거하지 말며, 시스템 설정을 변경하지 말고, 테스트 중인 앱이 전면에 있을 때만 입력을 보냅니다.
완료 조건: 두 개의 원본 녹화본이 존재하고, 각각 순간을 보여주며, 작업 트리 체크섬이 여전히 일치합니다.
4. 증거 만들기
init --out "$HANDTEST_ROOT/<그룹>" --id <N> --topic <케밥-케이스> --title "<일반 텍스트>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>". 그룹, OK 및 Not OK는 프로젝트 파일에서 가져옵니다. 셸이 명령어 사이에HANDTEST_ROOT를 유지하지 않을 수 있으므로 동일한 명령어 안에서 설정하십시오.- 각 녹화본에 대해 순간 주변에서
find-change <원본> --from <s> --to <s>. 동기화 시간은 단계의 로그 시간이 아니라 그림이 변하는 프레임입니다. pair --before <원본> --after <원본> --sync-before <s> --sync-after <s> --title ... --what ... --caption ... --out <폴더>/<id>_<주제>.mp4. 이 명령어는 비디오의 시간을 README.md와 PACKAGE.md에 채우고, 순간이 비디오의 어디에 있는지 출력합니다.- 각 측면당 하나의 정지 이미지, 순간 이후 한 박자, 원본 녹화본에서:
stills <원본> --at <s> --out <임시>/before, AFTER도 동일하게 실행합니다. 각 파일을 출력합니다. 그런 다음board --before <png> --after <png> --title ... --caption ... --out <폴더>/<id>_<주제>_BEFORE_AFTER.png. - 모든
<fill in: ...>표시를 채웁니다. 단어와 숫자에 대한 규칙은 EVIDENCE.md에 있습니다.
완료 조건: check <폴더>가 "ready for a person"을 출력합니다.
5. 리뷰어 검토
아무 사람이 보기 전에, 낯선 사람처럼 직접 리뷰합니다. 비디오에서 정지 이미지를 두 번 뽑습니다: stills <비디오> --every 1 --out <임시>, 그 다음 stills <비디오> --at <t-0.5> <t> <t+0.5> --out <임시>. 여기서 t는 원본 녹화본이 아닌 비디오에서의 순간 시간입니다(pair가 출력했으며, handtest.json에 video.change_at으로 저장됨). 모든 정지 이미지와 보드를 확인합니다.
- 각각이 캡션이 보라고 말하는 것을 보여줘야 합니다. 가려져 있거나, 비어 있거나, 잘못된 상태, 잘못된 언어, 변경 사항 위의 오버레이 등이 있으면 폴더를
archive하고 3단계부터 다시 녹화합니다. README에서 잘못된 사진을 설명하는 것보다 다시 녹화하는 것이 낫습니다. - 숫자는 그림과 일치해야 합니다. 불일치하는 경우 숫자가 잘못된 것입니다: 이유를 찾으십시오.
- 잘못된 그림과 함께 초록색 테스트가 통과한 것은 버그입니다. 사용자에게 결함으로 보고하십시오.
완료 조건: 모든 정지 이미지와 보드가 캡션이 주장하는 것을 보여주고, README의 모든 숫자가 그림과 일치합니다.
6. 인계
프로젝트의 증거가 저장되는 곳에 폴더를 넣습니다. 프로젝트 파일이 지정하는 곳에 PACKAGE.md를 게시하며, 폴더의 상대 경로만 명시하고 계정이나 절대 경로는 절대 명시하지 않습니다. PR의 yes 줄을 해당 경로와 대기 중인 사람으로 완성합니다(형식은 EVIDENCE.md의 "The PR section" 아래에 있음). 승인자에게 요청합니다. 수동 테스트가 열려 있는 동안 변경 사항은 병합되지 않은 상태로 유지됩니다(PR이 있는 경우 초안 PR).
완료 조건: 패키지가 게시되고, PR의 줄이 폴더를 명시하며, 승인자에게 요청되었고, 변경 사항의 어떤 부분도 병합되지 않았습니다.
7. 평결 기록
평결은 승인자의 것입니다. 그들이 주지 않은 OK를 절대 기록하지 마십시오.
- OK:
verdict <폴더> --ok --by "<누구>"(check에 실패한 폴더는 거부함), 그런 다음 프로젝트 파일이 OK 시 수행하라고 하는 것을 합니다(보통: PR을 준비 상태로 표시). - Not OK:
verdict <폴더> --not-ok --by "<누구>" --note "<그들이 말한 것>". 동일한 브랜치에서 수정하고, 폴더를archive한 후 3단계로 돌아갑니다. 재시도는 동일한 파일 이름을 다시 만듭니다; 이전 테이크는previous/로 이동합니다.init이 새 README.md를 작성했을 때,previous/<stamp>_README.md에서 여전히 유효한 줄을 복사합니다;pair가 시간을 다시 씁니다.
완료 조건: handtest.json에 사람의 평결이 저장되고 트래커가 일치합니다.
릴리스
각 수동 테스트의 폴더를 릴리스당 하나의 그룹 폴더 아래에 유지한 다음, report <그룹> --title "<릴리스>"를 실행합니다. REPORT.md와 하나의 자체 포함된 index.html을 작성하며, 대기 중인 수동 테스트가 먼저 옵니다. 자세한 내용은 EVIDENCE.md를 참조하십시오.