Maestro 버그 비디오은(는) 무엇을 하나요?

버그를 한 번도 본 적 없는 사람이 도움 없이 이해할 수 있는 MP4를 제작합니다: 버그 이름을 명시한 제목 카드, 각 단계를 평이한 언어로 설명, 결과를 명시하는 캡션, 그리고 마지막 프레임을 유지합니다. 비디오는 그 뒤에 있는 실행이 주장을 증명할 때만 증거가 되므로, Maestro 결과는 결과물의 일부입니다.

두 가지 모드가 하나의 워크플로우를 공유합니다:

모드	보여주는 내용	필요 조건
`explain`	버그 빌드의 한 번 실행	버그를 재현하는 플로우
`compare`	버그 빌드와 수정 빌드를 나란히 비교	동일한 플로우와 수정 사항이 포함된 빌드

전제 조건

버그를 재현하는 Maestro 플로우: 버그 빌드에서는 버그를 관찰하는 단계에서 실패하고, 수정 빌드에서는 통과해야 합니다. 그러한 플로우가 없으면 먼저 작성하십시오; 버그를 관찰하지 않는 실행의 비디오는 아무것도 증명하지 않습니다.
maestro가 PATH에 있어야 함 (프로젝트가 고정하는 경우 mise exec --를 통해 고정된 버전), ffmpeg 및 ffprobe와 drawtext 필터가 필요합니다. Android에서는 adb와 Python 3.10 이상도 필요합니다.
버그 빌드와, compare 모드의 경우 수정 빌드를 실행할 수 있는 기기 또는 시뮬레이터.

워크플로우

scripts/compose-bug-video와 같은 경로는 이 스킬의 디렉토리를 기준으로 합니다; 스크립트는 PATH에 없습니다.

플로우를 읽기 쉽게 만듭니다. 모든 명령에 사용자가 수행하거나 보는 내용을 설명하는 평이한 언어의 label:을 추가합니다. 플로우를 편집하기 전에 references/flow-tips.md를 읽으십시오; 레이블, 녹화 변형 및 속도에 대해 다룹니다.
버그 실행의 녹화 변형을 준비합니다. 플로우를 복사하고, 버그를 관찰하는 단계를 optional: true로 표시한 후 레이블을 예상: <올바른 동작> – <대신 발생하는 현상>으로 변경합니다. 실패하는 단계는 렌더러가 완료되기 전에 실행을 종료시킵니다; 선택적 단계는 비디오와 로그에 ⚠를 계속 표시합니다.
빌드를 설치합니다. 수정 이전의 커밋에서 버그 상태를 빌드합니다. 수정 사항이 즉시 복원하는 단일 라인이 아닌 이상 파일을 수동으로 되돌리지 마십시오. 기본 커밋의 git worktree에 자체 빌드 출력을 두면 두 빌드를 분리할 수 있습니다. 각 빌드를 별도의 기기에 설치하거나 녹화 사이에 재설치합니다.
한 번에 하나씩 녹화합니다. 각 녹화 전에 기기를 홈 화면 또는 테스트 중인 앱 화면에 둡니다: 플로우의 첫 번째 단계가 화면을 변경할 때까지 비디오는 이전에 기기에 표시된 내용을 보여줍니다. iOS 시뮬레이터에서는 Maestro의 렌더러를 사용합니다:
```
maestro --device <버그-기기> record --local <버그-변형.yaml> before.mp4
maestro --device <수정-기기> record --local <플로우.yaml> after.mp4
```
항상 --local을 전달하십시오: 없으면 Maestro가 녹화를 클라우드에 업로드하여 렌더링합니다.

Android 기기 또는 에뮬레이터에서는 scripts/record-maestro-run을 대신 사용하십시오. maestro record는 Android 실행의 끝을 자릅니다: screenrecord는 화면이 변경될 때만 프레임을 쓰고, 렌더러는 실행의 마지막 화면 이전인 마지막 프레임에서 멈춥니다. 이 스크립트는 화면 자체를 녹화하고, maestro test를 실행하고, 실행이 실제로 끝날 때까지 마지막 프레임을 유지하고, Maestro의 commands.json에서 단계를 그립니다:
```
scripts/record-maestro-run --device <버그-기기> --flow <버그-변형.yaml> --out before.mp4
scripts/record-maestro-run --device <수정-기기> --flow <플로우.yaml> --out after.mp4 --maestro "mise exec -- maestro"
```
비디오는 Maestro의 시작 없이 플로우의 첫 번째 단계에서 시작합니다. Maestro의 종료 코드로 종료됩니다. Android 17과 같이 기기의 screenrecord가 허용하는 경우 녹화에 시간 제한이 없습니다. 이전 버전은 180초 후에 녹화를 중지합니다.

${MAESTRO_PASSWORD}와 같은 테스트 계정 비밀번호를 입력하는 플로우는 해당 inputText에 label:이 필요합니다: maestro record는 단계 목록에서 확인된 텍스트를 출력하므로, 레이블이 없는 단계는 비디오에 비밀이 표시됩니다. record-maestro-run은 확인된 값을 표시하지 않으며, 입력된 텍스트를 기록하는 Maestro 로그는 삭제하는 임시 디렉토리에 보관합니다.

녹화를 순차적으로 실행하십시오; 별도로 시작된 두 개의 Maestro 프로세스는 동일한 드라이버 포트를 놓고 경쟁하여 두 실행 모두 중단됩니다. 시작하기 전에 이전 실행이 아직 살아 있는지 확인하고 (pgrep -fl maestro), 시작한 남은 프로세스를 중지하십시오.
실행이 주장을 증명하는지 확인합니다. 버그 녹화는 모든 설정 단계가 통과되고 버그 단계가 경고됨 (Maestro 렌더러의 ✅ 및 ⚠, record-maestro-run의 녹색 및 호박색 표시)과 함께 화면에 버그가 보여야 합니다; 수정 녹화는 모든 단계가 통과되어야 합니다. 둘 중 하나라도 다르면 비디오가 오해를 불러일으킬 수 있습니다: 중단하고 플로우나 빌드를 수정하십시오.

비디오를 합성합니다 scripts/compose-bug-video를 사용하여:

scripts/compose-bug-video explain --video before.mp4 \
  --title "<앱> · <화면>" --subtitle "버그: <사용자가 말할 한 문장>" \
  --steps "<한 줄로 된 단계>" --caption "<시청자가 주목해야 할 점>" --out bug.mp4

scripts/compose-bug-video compare --before before.mp4 --after after.mp4 \
  --title "<앱> · <화면>" --subtitle "버그: <한 문장>" \
  --steps "양쪽 동일 단계: <단계>" \
  --caption "왼쪽: <문제점>.   오른쪽: <수정 사항이 하는 일>." --out before-after.mp4

팀 외부 사람을 위해 제목 카드와 캡션을 작성하십시오: 코드가 아닌 화면 이름과 보이는 증상을 명시합니다. 배너 레이블은 기본적으로 "BEFORE · 현재 앱" 및 "AFTER · 수정 적용"입니다 (--before-label, --after-label); --hold는 마지막 프레임의 일시 정지를 설정합니다.

결과를 전달하기 전에 확인합니다. 제목 프레임과 마지막 프레임을 추출하고 (ffmpeg -ss 1 -i out.mp4 -frames:v 1 title.png, ffmpeg -sseof -1 -i out.mp4 -frames:v 1 end.png) 확인합니다: 텍스트가 완전하고 읽기 쉬워야 하며, 마지막 프레임에 버그, 또는 버그와 수정 사항이 함께 표시되어야 합니다.

완료

비디오 경로, 길이, 각 측면이 보여주는 빌드 또는 커밋, 그리고 각 실행의 Maestro 결과를 보고합니다. 출력물은 로컬에 유지됩니다; 게시하거나 첨부하는 것은 사용자의 결정입니다.

Maestro 버그 비디오