ahmadrosid/nakama

PR을 위한 브라우저 동영상 증거

UI 수정 사항을 증명하는 짧고 재생 가능한 브라우저 동영상을 녹화하고, PR 설명에 첨부한 후 실제 본문을 확인합니다. 사용자가 명시적으로 요청하지 않는 한 녹화를 위해 애플리케이션 코드를 변경하지 마십시오.

참고 실행: PR #723 (/automations 확장 장기 실행 스크롤).

전제 조건

• 대상 저장소에 푸시 권한으로 인증된 gh
• 작업 트리에 Bun + 저장소 의존성 설치 완료 (bun install)
• 호스트에 Google Chrome (또는 Chromium) 설치
• PATH에 ffmpeg (webm → H.264 MP4 변환용)
• /tmp 아래 격리된 디렉토리에 Playwright (저장소에 추가하지 마십시오):

mkdir -p /tmp/<run>/playwright
cd /tmp/<run>/playwright
npm i playwright
npx playwright install ffmpeg

프로세스

1. git worktree로 격리

메인 체크아웃을 깨끗하게 유지합니다.

cd "$(git rev-parse --show-toplevel)"
git fetch origin main
git worktree add -b <branch> .worktrees/<slug> origin/main   # 또는 수정 브랜치에 연결
cd .worktrees/<slug>

서버와 녹화 작업은 해당 worktree 내에서만 수행합니다.

2. 먼저 Fixture와 UI 검사

데이터를 임의로 생성하기 전에:

1. 테스트 대상 페이지를 읽습니다 (레이블, 확장 컨트롤, 스크롤 컨테이너).
2. 동일한 기능에 대한 기존 테스트 fixture / factory를 확인합니다.
3. 공개 HTTP API를 통해 시딩하는 것을 우선합니다. API로 필요한 행을 생성할 수 없는 경우에만 (예: 완료된 자동화 실행에 거대한 output이 있는 경우) 격리된 NAKAMA_CONFIG_DIR에서 일회성 SQLite 삽입을 대체 수단으로 사용합니다.

3. 결정론적 긴 콘텐츠 시딩

스크롤 / 오버플로 증명의 경우 fixture가 패널보다 높아야 합니다.

• 시작 부분 근처에 고유한 상단 마커 배치: SCROLL_PROOF_MARKER_TOP
• 끝 부분에 고유한 하단 마커 배치: SCROLL_PROOF_MARKER_BOTTOM
• scrollHeight - clientHeight가 충분히 크도록 (수천 픽셀) 충분한 본문 텍스트 사용

실행 출력의 예시 구조:

# SCROLL_PROOF_MARKER_TOP — 긴 자동화 실행 출력

## 섹션 1
...

## 섹션 80
...

# SCROLL_PROOF_MARKER_BOTTOM — 긴 콘텐츠 끝

운영자의 실제 ~/.nakama 데이터에 시딩하지 마십시오. 항상 /tmp/<run>/ 아래에 새로운 NAKAMA_CONFIG_DIR을 사용하십시오.

4. 격리된 로컬 서버 시작

사용 가능한 포트를 선택합니다. 4310 / 3000 / 3003에 이미 리스너가 있는 경우 기본 스택을 사용하지 마십시오.

RUN=/tmp/<run>
API_PORT=4330
WEB_PORT=3014
mkdir -p "$RUN/nakama-data" "$RUN/logs"

# 셸 종료 후에도 프로세스 유지 (일반 nohup ... & 는 여기서 종료됨)
setsid nohup env NAKAMA_CONFIG_DIR="$RUN/nakama-data" NAKAMA_PORT=$API_PORT \
  bun run apps/server/src/index.ts \
  >"$RUN/logs/server.log" 2>&1 < /dev/null &

setsid nohup env VITE_API_URL="http://127.0.0.1:${API_PORT}" \
  bun run --cwd apps/web dev -- --host 127.0.0.1 --port $WEB_PORT \
  >"$RUN/logs/web.log" 2>&1 < /dev/null &

curl -sf http://127.0.0.1:$API_PORT/health가 성공하고 웹 오리진이 응답할 때까지 기다립니다. 새 설정: POST /v1/auth/setup 후 Cookie + X-CSRF-Token + X-Org-Id를 사용하여 제공자 / 프로필 / 자동화를 생성하거나 (또는 fixture 재사용).

5. Playwright로 녹화 (H.264 MP4)

/tmp/<run>/ 아래에만 레코더를 구성합니다. 절대 커밋하지 마십시오.

const browser = await chromium.launch({
  channel: "chrome", // Chrome이 설치된 경우
  headless: false,
  args: ["--disable-gpu"],
});
const context = await browser.newContext({
  viewport: { width: 1440, height: 900 },
  recordVideo: { dir: rawDir, size: { width: 1440, height: 900 } },
});

규칙:

1. 테스트 대상 실제 UI 경로를 구동합니다 (역할/텍스트 로케이터 사용).
2. 움직임을 가시적으로 만듭니다 — 마우스 휠 또는 단계별 스크롤, 단일 보이지 않는 점프만으로는 안 됩니다.
3. 스크롤이 이동했는지 (scrollTop 델타) 확인하고 하단 마커에 도달 가능한지 확인합니다.
4. context.close() 전에 page.video()?.path()를 캡처합니다.
5. 변환: ffmpeg -y -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4
6. results.json + 전후 스크린샷을 artifacts/e2e-<id>/ 아래에 작성합니다.

WebM만으로는 GitHub 재생에 충분하지 않습니다. H.264 + yuv420p를 제공하십시오.

6. 무엇이든 주장하기 전에 동영상 검증

ffprobe -v error -show_entries stream=codec_name,width,height \
  -show_entries format=duration -of json out.mp4
# 초기 / 후기 프레임 추출 및 확인
ffmpeg -y -ss 00:00:02 -i out.mp4 -vframes 1 frame-early.png
ffmpeg -y -ss 00:00:08 -i out.mp4 -vframes 1 frame-late.png

다음 조건을 모두 충족해야 통과:

• 코덱이 h264
• 재생 시간이 상호작용을 볼 수 있을 만큼 충분히 길음
• 초기 프레임이 시작 상태(예: 상단 마커 / 확장된 패널)를 보여줌
• 후기 프레임이 스크롤 진행 상황(하단 마커 또는 고급 섹션)을 보여줌
• results.json이 실제 scrollTop 델타(또는 동등한 증명 메트릭)를 보고함

7. GitHub 사용자 첨부 파일에 업로드

문서화되지 않았지만 푸시 권한이 있으면 이미지/동영상에 대해 토큰 인증이 작동합니다:

TOKEN=$(gh auth token)
REPO_ID=$(gh api repos/<owner>/<repo> --jq .id)
MP4=artifacts/e2e-<id>/<name>.mp4

UPLOAD_JSON=$(curl -sS -X POST \
  "https://uploads.github.com/user-attachments/assets?name=$(basename "$MP4")&repository_id=${REPO_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: video/mp4" \
  -H "Accept: application/vnd.github+json" \
  --data-binary @"${MP4}")

VIDEO_URL=$(printf '%s' "$UPLOAD_JSON" | bun -e 'console.log(JSON.parse(await Bun.stdin.text()).url)')
echo "$VIDEO_URL"  # https://github.com/user-attachments/assets/<uuid>

URL을 저장합니다. HEAD/GET으로 에셋을 확인하여 동영상 콘텐츠 유형이 반환되는지 확인합니다.

8. PR 설명 업데이트

표시된 단계와 함께 짧은 브라우저 증거 섹션을 추가하고 https://github.com/user-attachments/assets/... URL을 자체 행에 추가합니다 (GitHub가 플레이어를 삽입합니다). 본문은 파일을 통해 작성하는 것이 좋습니다:

gh api repos/<owner>/<repo>/pulls/<n> --method PATCH --input body.json
# 또는: gh pr edit <n> --body-file /tmp/pr-body.md

본문의 나머지 부분은 .agents/skills/adhd-pr-description/SKILL.md를 따르십시오.

9. 라이브 PR 본문 확인

gh api repos/<owner>/<repo>/pulls/<n> --jq .body | rg 'user-attachments/assets/<uuid>|Browser proof'

이 검사가 통과할 때까지 성공을 보고하지 마십시오.

예시: automations expanded-run 스크롤

1. 수정 브랜치 (또는 이 스킬을 위한 문서 전용 브랜치)의 Worktree.
2. 격리된 API 4330 + 웹 3014, 새로운 NAKAMA_CONFIG_DIR.
3. POST /v1/auth/setup → 제공자 → Long output digester 자동화 생성.
4. output이 긴 마크다운이고 SCROLL_PROOF_MARKER_TOP / SCROLL_PROOF_MARKER_BOTTOM을 포함하는 하나의 실행을 삽입/완료.
5. Playwright: /automations 열기 → 자동화 선택 → 실행 확장 → 하단 마커가 보일 때까지 세부 정보 패널을 휠 스크롤.
6. H.264 MP4로 변환, 프레임 검사, 업로드, PR 본문 패치, 확인.

정리

1. 선택한 포트에서 격리된 API/웹 리스너를 종료합니다.
2. /tmp/<run>/ 및 프로필 artifacts/e2e-<id>/를 로컬 증거로 남겨 둡니다 (동영상이나 레코더 스크립트는 커밋하지 마십시오).
3. 브랜치가 병합되거나 폐기되면 worktree를 제거합니다: git worktree remove .worktrees/<slug>

정직성 규칙

1. 프레임이나 ffprobe + 스크린샷을 확인하지 않고 브라우저 증거를 주장하지 마십시오.
2. 직접 업로드하고 라이브 PR 본문에서 다시 가져오지 않은 user-attachments URL을 붙여넣지 마십시오.
3. 요청이 시각적 증거였을 때 녹색 단위 테스트를 동영상의 대체물로 취급하지 마십시오.
4. 스크롤이 이동하지 않았거나, 마커가 잘못되었거나, MP4가 비어 있거나 손상된 경우 — 실패했다고 말하십시오. 누그러뜨리지 마십시오.
5. 사용자가 제품 수정을 요청하지 않는 한 "동영상을 쉽게 만들기 위해" 애플리케이션 코드를 수정하지 마십시오.
6. 운영자의 실제 Nakama 구성 디렉토리를 건드리지 마십시오.