---
name: Screenshot Validation
slug: screenshot-validation
category: Quality
description: Screenshot Validation checks evidence images and viewer HTML files for quality standards before committing, catching issues like small or blank screenshots and viewer rendering errors. Use it after generating PR evidence or new trace viewer HTML.
github: "https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/screenshot-validation"
language: Python
stars: 3064
forks: 266
install: "npx degit https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/screenshot-validation ~/.claude/skills/screenshot-validation"
installs_to: ~/.claude/skills/screenshot-validation
source_path: .agents/skills/screenshot-validation/SKILL.md
collection_size: 11
category_size: 1354
collection_url: "https://dirskills.com/collections/liaohch3/claude-tap"
added: 2026-08-17T07:09:17.415Z
last_synced: 2026-08-17T07:09:17.415Z
canonical_url: "https://dirskills.com/skills/screenshot-validation"
---

# Screenshot Validation

Screenshot Validation checks evidence images and viewer HTML files for quality standards before committing, catching issues like small or blank screenshots and viewer rendering errors. Use it after generating PR evidence or new trace viewer HTML.

**Install:**

```bash
npx degit https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/screenshot-validation ~/.claude/skills/screenshot-validation
```

## README

# Screenshot Validation

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.

## Image quality check

Checks PNG/JPG/GIF/WEBP files for:
- **Minimum dimensions**: 400x400 pixels (hard fail)
- **Desktop viewport width**: >= 1280px (warning if narrower)
- **File size**: <= 5MB (warning if larger)
- **Blankness detection** (PNG only): fails if > 90% of pixels are white/transparent

### Run on specific files or directories

```bash
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
```

### Run on git-staged images

```bash
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.

## Viewer HTML rendering verification

Uses Playwright (headless Chromium) to verify that generated viewer HTML files actually render correctly — not just raw JSON or Python errors.

Checks:
- No JavaScript errors on page load
- Normal traces render a sidebar with entries and a detail panel
- Empty embedded traces render the explicit "No API calls captured" state
- Body text doesn't contain raw JSON dumps or Python tracebacks

### Run

```bash
uv run python scripts/verify_screenshots.py .traces/trace_*.html
```

Requires Playwright to be installed (`uv pip install playwright && playwright install chromium`).

## Typical workflow

After generating new evidence for a PR:

```bash
# 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/
```

## Fixing common failures

| 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 |