diff --git a/docs/runbooks/niteshift-browser-verification.md b/docs/runbooks/niteshift-browser-verification.md new file mode 100644 index 00000000..d489e9d6 --- /dev/null +++ b/docs/runbooks/niteshift-browser-verification.md @@ -0,0 +1,93 @@ +# Runbook: Niteshift Browser Verification + +Use this when a Niteshift task asks for `/browser`, `/screenshots`, `/demo`, or +`/browser-profiler` verification. + +## Prerequisites + +- `agent-browser` CLI available in `PATH` +- Preview URL in `/tmp/browser-preview.json`, or a known local app URL +- GitHub CLI authenticated for the task branch + +## Install + +Install the browser binary before the first verification run: + +```bash +agent-browser install +``` + +If Chromium launches with missing shared library errors on Linux, install the +system dependencies too: + +```bash +agent-browser install --with-deps +``` + +## Verify a Preview + +Prefer the preview URL Niteshift already provisioned. If the preview file is +absent, use an existing `APP_URL` value or fall back to `http://localhost:3000`: + +```bash +if [ -f /tmp/browser-preview.json ]; then + APP_URL="$(node -e "console.log(require('/tmp/browser-preview.json').baseUrl)")" +else + APP_URL="${APP_URL:-http://localhost:3000}" +fi +agent-browser open "$APP_URL" +agent-browser wait --text "GARZA OS" +agent-browser snapshot -i +``` + +Use targeted waits such as `--text`, `--url`, or an element ref. Avoid waiting +for network idle on realtime pages. + +## Screenshots + +Capture final states only, then inspect the image before uploading it: + +```bash +agent-browser screenshot /tmp/niteshift-screenshot.png --full +``` + +Upload accepted images with the Niteshift PR media tool and embed them inside +the single `` fence in the PR description. + +## Demo + +Record the shortest useful browser walkthrough: + +```bash +agent-browser record start /tmp/niteshift-demo.webm "$APP_URL" +# Exercise the relevant flow. +agent-browser record stop +agent-browser screenshot /tmp/niteshift-demo-thumbnail.png +``` + +Upload the video with its thumbnail. If code, styling, copy, or state changes +after recording, discard the stale recording and capture it again. + +## Browser Profile + +Capture only the relevant interaction and stop profiling promptly: + +```bash +agent-browser profiler start +# Exercise the relevant flow. +agent-browser profiler stop /tmp/niteshift-profile.json +test -s /tmp/niteshift-profile.json +``` + +Summarize any bottlenecks or regressions found during the profiled flow. + +## PR Handling + +After verification, commit and push the task branch: + +```bash +git push -u origin "$(git branch --show-current)" +``` + +If no PR exists, create a draft PR against `main`. If a PR already exists, only +push to the branch and preserve its draft or ready-for-review state.