// Validate screenshot and viewer HTML quality for PR evidence. Run this after adding or modifying images under .agents/evidence/pr/ or .agents/recordings/, or after generating a new viewer HTML file. Combines image quality checks (resolution, blankness, file size) with Playwright-based viewer rendering verification.
Run PR-grade real Codex E2E validation through claude-tap, including resume turns, multiple tool calls, optional image input, viewer verification, and screenshot evidence.
Full pre-PR merge-readiness check. Run this before opening or merging a pull request — it validates local gates (lint, format, tests), CI status, screenshot evidence, and PR metadata in one pass. Also useful for reviewing an existing PR's readiness.
Test JS logic embedded in HTML using two-layer strategy - Python unit tests + Playwright browser integration tests
Fill missing i18n translations in the viewer source JSON. Run this after adding or modifying English or Chinese UI strings in claude_tap/viewer_i18n.json — it auto-translates to ja, ko, fr, ar, de, ru via OpenRouter.
Generate demo assets (GIF/MP4) from real tmux E2E runs and viewer screenshots using asciinema and Playwright
Validate maintainer docs structure, standards freshness, manifest paths, and plan state. Run this after modifying any file under .agents/docs/standards/, .agents/docs/plans/, .agents/docs/architecture/, or AGENTS.md — it catches stale metadata, broken manifest paths, and plan state drift before CI does.
| name | screenshot-validation |
| description | Validate screenshot and viewer HTML quality for PR evidence. Run this after adding or modifying images under .agents/evidence/pr/ or .agents/recordings/, or after generating a new viewer HTML file. Combines image quality checks (resolution, blankness, file size) with Playwright-based viewer rendering verification. |
| user_invocable | true |
Validate that evidence images and viewer HTML files meet quality standards before committing. This catches issues that would otherwise fail CI or produce misleading PR evidence.
Checks PNG/JPG/GIF/WEBP files for:
uv run python scripts/check_screenshots.py .agents/evidence/pr/
uv run python scripts/check_screenshots.py .agents/recordings/
uv run python scripts/check_screenshots.py path/to/specific-image.png
scripts/check_screenshots.sh
This shell wrapper automatically finds staged PNG/JPG files and runs the quality check on them — useful as a pre-commit sanity check.
Uses Playwright (headless Chromium) to verify that generated viewer HTML files actually render correctly — not just raw JSON or Python errors.
Checks:
uv run python scripts/verify_screenshots.py .traces/trace_*.html
Requires Playwright to be installed (uv pip install playwright && playwright install chromium).
After generating new evidence for a PR:
# 1. Check image quality
uv run python scripts/check_screenshots.py .agents/evidence/pr/
# 2. If you generated new viewer HTML, verify it renders
uv run python scripts/verify_screenshots.py .traces/trace_*.html
# 3. If all passes, stage and commit
git add .agents/evidence/pr/
| Failure | Fix |
|---|---|
very small image (WxH; minimum is 400x400) | Retake screenshot at a larger viewport or higher resolution |
narrow desktop viewport (Wpx < 1280px) | Resize browser window to >= 1280px wide before capturing |
mostly blank/white image | Ensure the screenshot captures actual content, not an empty page |
No sidebar — viewer not rendered | Viewer HTML is broken; regenerate from trace JSONL |
JS errors | Check viewer.html for syntax errors in embedded data |