ms2sato/browser-qa

Browser QA

Manual browser verification procedure for UI changes using Chrome DevTools MCP.

When to Use

• Acceptance criteria include manual verification
• PR modifies packages/client/src/components/
• Visual or interaction behavior needs confirmation beyond automated tests

Procedure

1. Start Dev Server

cd <repository-root>
bun run dev

Check the startup log for the actual port — Vite may auto-increment if the default port (5173) is in use:

Port 5173 is in use, trying another one...
  ➜  Local:   http://localhost:5174/

Also check .env for custom port configuration (CLIENT_PORT, PORT).

2. Navigate to the UI

mcp: navigate_page → http://localhost:<port>
mcp: take_screenshot → confirm page loaded

For specific pages, navigate directly via client route (SPA routing works):

mcp: navigate_page → http://localhost:<port>/sessions/<id>

3. Interact and Verify

Use Chrome DevTools MCP tools:

| Action | Tool | Tips | |--------|------|------| | Click element | click | Use take_snapshot first to get element UIDs | | Type text | type_text | Click the input first to focus | | Fill form field | fill | Target by UID from snapshot | | Wait for async | wait_for | Wait for selector to appear | | Check errors | list_console_messages | Look for JS errors | | Screenshot | take_screenshot | Capture before/after states |

4. Verify Acceptance Criteria

For each manual verification criterion:

1. Reproduce the scenario described
2. Take a screenshot confirming the expected behavior
3. Check list_console_messages for unexpected errors

5. Cleanup

Stop the dev server when done (kill the background process or Ctrl+C).

Screenshot Persistence & PR Upload

All screenshots should be saved to disk for later upload to the PR.

Setup

Before starting QA, prepare the screenshot directory:

rm -rf .qa-screenshots && mkdir -p .qa-screenshots

Taking Screenshots

Always use filePath to save to .qa-screenshots/:

take_screenshot with filePath: ".qa-screenshots/{descriptive-name}.png"

Use descriptive, hyphenated names:

• restart-all-button.png, restart-result-toast.png
• error-{description}.png (for error states)

Selective Screenshot Policy

Only take screenshots for areas relevant to the PR's change scope:

• Bug fix PRs: Capture before/after states of the fixed behavior
• UI change PRs: Capture the changed areas
• Always capture: Error states encountered, regardless of relevance

Uploading to PR

After QA, upload screenshots to the PR:

./scripts/upload-qa-screenshots.sh <PR_NUMBER>

This script:

1. Auto-detects the repository from git remote (override with GITHUB_REPOSITORY env var)
2. Creates a qa-screenshots GitHub Release if it doesn't exist (one-time, used as image hosting)
3. Uploads all .png files from .qa-screenshots/ with unique names
4. Posts a PR comment with static thumbnails and expandable full-size images via <details>

Note: GitHub Release assets are served with Content-Disposition: attachment, so <a href> links trigger downloads instead of displaying images. The script uses <details><summary> to work around this.

If the PR number is not known, detect it:

gh pr view --json number -q '.number'

Re-taking Screenshots

When re-taking screenshots (e.g., after implementation changes), minimize the previous screenshot comment on the PR before uploading new ones. This prevents reviewers from seeing outdated screenshots.

# 1. Find the previous screenshot comment's node ID
gh api graphql -f query='query { repository(owner: "OWNER", name: "REPO") { pullRequest(number: PR_NUM) { comments(first: 50) { nodes { id body createdAt } } } } }' \
  --jq '.data.repository.pullRequest.comments.nodes[] | select(.body | test("qa-screenshots")) | .id'

# 2. Minimize it as OUTDATED
gh api graphql -f query='mutation { minimizeComment(input: {subjectId: "NODE_ID", classifier: OUTDATED}) { minimizedComment { isMinimized } } }'

# 3. Upload new screenshots
./scripts/upload-qa-screenshots.sh <PR_NUMBER>

Common Issues

• Port conflict: Check startup log for actual port. Vite auto-increments.
• Blank page: Run bun run --filter '@agent-console/shared' build first — client depends on shared types.
• API errors: Ensure backend is also running (dev script starts both, but check logs).