Browser Video Proof

Browser video proof for PRs

Record a short, playable browser video that proves a UI fix, attach it to the PR description, and verify the live body. Do not change application code for the recording unless the user explicitly asks.

Reference run: PR #723 (/automations expanded long-run scroll).

Prerequisites

• gh authenticated with push access to the target repo
• Bun + repo deps installed in the worktree (bun install)
• Google Chrome (or Chromium) on the host
• ffmpeg on PATH (for webm → H.264 MP4)
• Playwright in an isolated dir under /tmp (do not add it to the repo):

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

Process

1. Isolate with a git worktree

Keep the main checkout clean.

cd "$(git rev-parse --show-toplevel)"
git fetch origin main
git worktree add -b  .worktrees/ origin/main   # or attach to the fix branch
cd .worktrees/

Work only inside that worktree for servers and recording.

2. Inspect fixtures and UI first

Before inventing data:

1. Read the page under test (labels, expand controls, scroll containers).
2. Check existing test fixtures / factories for the same feature.
3. Prefer seeding via the public HTTP API. Fall back to a one-off SQLite insert

in an isolated NAKAMA_CONFIG_DIR only when no API can create the needed row (e.g. a completed automation run with huge output).

3. Seed deterministic tall content

For scroll / overflow proofs, the fixture must be taller than the pane.

• Put a unique top marker near the start: SCROLL_PROOF_MARKER_TOP
• Put a unique bottom marker at the end: SCROLL_PROOF_MARKER_BOTTOM
• Use enough body text that scrollHeight - clientHeight is large (thousands of px)

Example shape for run output:

# SCROLL_PROOF_MARKER_TOP — long automation run output

## Section 1
...

## Section 80
...

# SCROLL_PROOF_MARKER_BOTTOM — end of tall content

Never seed into the operator's real ~/.nakama data. Always use a fresh NAKAMA_CONFIG_DIR under /tmp//.

4. Start isolated local servers

Pick free ports. Do not steal the default stack if something already listens on 4310 / 3000 / 3003.

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

# Keep processes alive after the shell exits (plain nohup ... & dies here)
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 "$RUN/logs/web.log" 2>&1 /` only. Never commit it.

```js
const browser = await chromium.launch({
  channel: "chrome", // if Chrome is installed
  headless: false,
  args: ["--disable-gpu"],
});
const context = await browser.newContext({
  viewport: { width: 1440, height: 900 },
  recordVideo: { dir: rawDir, size: { width: 1440, height: 900 } },
});

Rules:

1. Drive the real UI path under test (role/text locators).
2. Make motion visible — mouse wheel or stepped scroll, not a single invisible jump only.
3. Assert scroll moved (scrollTop delta) and that the bottom marker becomes reachable.
4. Capture page.video()?.path() before context.close().
5. Convert: ffmpeg -y -i in.webm -c:v libx264 -pix_fmt yuv420p out.mp4
6. Write results.json + before/after screenshots under artifacts/e2e-/.

WebM alone is not enough for GitHub playback. Ship H.264 + yuv420p.

6. Validate the video before claiming anything

ffprobe -v error -show_entries stream=codec_name,width,height \
  -show_entries format=duration -of json out.mp4
# Extract early / late frames and look at them
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

Pass only if:

• codec is h264
• duration is long enough to see the interaction
• early frame shows the start state (e.g. top marker / expanded pane)
• late frame shows scroll progress (bottom marker or advanced sections)
• results.json reports a real scrollTop delta (or equivalent proof metric)

7. Upload to GitHub user-attachments

Undocumented but token-auth works for images/video when you have push access:

TOKEN=$(gh auth token)
REPO_ID=$(gh api repos// --jq .id)
MP4=artifacts/e2e-/.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/

Save the URL. Confirm a HEAD/GET on the asset returns a video content type.

8. Update the PR description

Add a short Browser proof section with the steps shown and the bare https://github.com/user-attachments/assets/... URL on its own line (GitHub embeds the player). Prefer writing the body via a file:

gh api repos///pulls/ --method PATCH --input body.json
# or: gh pr edit  --body-file /tmp/pr-body.md

Follow .agents/skills/adhd-pr-description/SKILL.md for the rest of the body.

9. Verify the live PR body

gh api repos///pulls/ --jq .body | rg 'user-attachments/assets/|Browser proof'

Do not report success until this check passes.

Example: automations expanded-run scroll

1. Worktree on the fix branch (or docs-only branch for this skill).
2. Isolated API 4330 + web 3014, fresh NAKAMA_CONFIG_DIR.
3. POST /v1/auth/setup → provider → create automation Long output digester.
4. Insert/complete one run whose output is the long markdown with

SCROLL_PROOF_MARKER_TOP / SCROLL_PROOF_MARKER_BOTTOM.

1. Playwright: open /automations → select the automation → Expand run →

wheel-scroll the detail pane until the bottom marker is in view.

1. Convert to H.264 MP4, inspect frames, upload, patch PR body, verify.

Cleanup

1. Kill the isolated API/web listeners on the ports you chose.
2. Leave /tmp// and profile artifacts/e2e-/ as local evidence

(do not commit videos or recorder scripts).

1. Remove the worktree when the branch is merged or abandoned:

git worktree remove .worktrees/

Honesty rules

1. Never claim browser proof without watching frames or ffprobe + screenshots.
2. Never paste a user-attachments URL you did not upload and re-fetch from the live PR body.
3. Never treat a green unit test as a substitute for the video when the ask was visual proof.
4. If scroll did not move, markers are wrong, or the MP4 is empty/corrupt — say it failed. Do not soften.
5. Do not modify application code “to make the video easier” unless the user asked for a product fix.
6. Do not touch the operator’s real Nakama config dir.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ahmadrosid
• Source: ahmadrosid/nakama
• License: MIT
• Homepage: https://ahmadrosid.github.io/nakama

Install and usage instructions live in the source repository linked above.