screenshot-handling

# Screenshot Handling ## ⚠️ CRITICAL REQUIREMENT ⚠️ **SAVING SCREENSHOTS TO PROJECT ROOT IS FORBIDDEN.** **ALL screenshots MUST be saved to the `screenshots/` folder. There are NO exceptions.** ### Validation Checklist Before capturing ANY screenshot, verify: 1. ✅ `screenshots/` folder exists (create with `mkdir -p screenshots/`) 2. ✅ Screenshot command includes `screenshots/` in the path 3. ✅ Path format: `screenshots/filename.png` (NOT `filename.png`) ### Correct vs Incorrect Examples ✅ **CORRECT - Screenshots in `screenshots/` folder:** - `screenshots/mainmenu-verification.png` - `screenshots/timer-test.png` - `screenshots/game-over-state.png` - `screenshots/ui-validation.png` ❌ **INCORRECT - Screenshots in project root (FORBIDDEN):** - `mainmenu-verification.png` (project root) - `timer-test.png` (project root) - `game-over-state.png` (project root) - `verification.png` (project root) **If you discover screenshots in the project root, move them immediately to `screenshots/` folder.** **Screenshot path**: Use **project root or absolute path** for the screenshot directory so CWD does not cause wrong locations. When saving to `screenshots/`, ensure CWD is project root. **Pre-completion (web tasks)**: For frontend/web tasks, do not skip browser verification; if agent-browser is loaded, at least one browser action (open, navigate, submit, or capture) must be performed before marking complete, unless documented as impossible (e.g. backend down) with fallback. For scaffold-only tasks, at least open the app URL and capture one screenshot to confirm the shell renders. ## Overview Screenshots should always be saved to a dedicated `screenshots/` folder instead of the project root directory. This keeps the project root clean and organized, making it easier to manage and locate screenshot files. **Problem**: Screenshots saved to project root create clutter and make it difficult to manage project files. **Solution**: Always save screenshots to `screenshots/` folder, creating it if it doesn't exist. ## Required Behavior **ALWAYS** save screenshots to the `screenshots/` folder: - ✅ `screenshots/mainmenu-verification.png` - ✅ `screenshots/timer-test.png` - ✅ `screenshots/game-over-state.png` - ❌ `mainmenu-verification.png` (project root) - ❌ `timer-test.png` (project root) ## Folder Creation **Always ensure the `screenshots/` folder exists before saving screenshots.** ### Bash/Shell ```bash mkdir -p screenshots/ agent-browser screenshot screenshots/mainmenu-verification.png ``` ### Node.js/TypeScript ```typescript import fs from 'fs'; // Create folder if it doesn't exist fs.mkdirSync('screenshots', { recursive: true }); // Then capture screenshot await page.screenshot({ path: 'screenshots/mainmenu-verification.png' }); ``` ### Python ```python import os # Create folder if it doesn't exist os.makedirs('screenshots', exist_ok=True) # Then capture screenshot page.screenshot(path='screenshots/mainmenu-verification.png') ``` ## Methods Covered ### agent-browser Screenshot Commands **CRITICAL: ALWAYS create the `screenshots/` folder FIRST, then specify the `screenshots/` folder path:** ```bash # STEP 1: Create folder first (MANDATORY) mkdir -p screenshots/ # STEP 2: Capture screenshot to screenshots/ folder (path MUST include screenshots/) agent-browser screenshot screenshots/mainmenu-verification.png agent-browser screenshot screenshots/timer-test.png agent-browser screenshot screenshots/game-over-state.png # Full page screenshot (also in screenshots/ folder) agent-browser screenshot --full screenshots/full-page.png ``` **❌ FORBIDDEN - Never save to project root:** ```bash # WRONG - Missing screenshots/ folder in path agent-browser screenshot mainmenu-verification.png # ❌ Saves to project root agent-browser screenshot verification.png # ❌ Saves to project root ``` **✅ CORRECT - Always include screenshots/ in path:** ```bash # RIGHT - Includes screenshots/ folder in path mkdir -p screenshots/ # ✅ Create folder first agent-browser screenshot screenshots/mainmenu-verification.png # ✅ Saves to screenshots/ ``` **Reference**: See `agent-browser` skill for complete screenshot command syntax. ### Playwright Screenshot Methods **Always use `screenshots/` folder path:** ```typescript import { chromium } from 'playwright'; import fs from 'fs'; // Create folder if it doesn't exist fs.mkdirSync('screenshots', { recursive: true }); const browser = await chromium.launch(); const page = await browser.newPage(); await page.goto('http://localhost:5173'); // Capture screenshot to screenshots/ folder await page.screenshot({ path: 'screenshots/mainmenu-verification.png' }); // Full page screenshot await page.screenshot({ path: 'screenshots/full-page.png', fullPage: true }); await browser.close(); ``` ### Puppeteer Screenshot Methods **Always use `screenshots/` folder path:** ```typescript import puppeteer from 'puppeteer'; import fs from 'fs'; // Create folder if it doesn't exist fs.mkdirSync('screenshots', { recursive: true }); const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.goto('http://localhost:5173'); // Capture screenshot to screenshots/ folder await page.screenshot({ path: 'screenshots/mainmenu-verification.png' }); // Full page screenshot await page.screenshot({ path: 'screenshots/full-page.png', fullPage: true }); await browser.close(); ``` ### Other Screenshot Capture Tools **For any other screenshot capture method:** 1. Create `screenshots/` folder if it doesn't exist 2. Always specify `screenshots/filename.png` as the output path 3. Never save to project root ## Naming Conventions **Use descriptive filenames with context:** - ✅ `screenshots/mainmenu-verification.png` - Clear purpose - ✅ `screenshots/timer-test-10seconds.png` - Includes test context - ✅ `screenshots/game-over-state.png` - Describes state - ✅ `screenshots/ui-validation-mainmenu.png` - Includes validation context - ✅ `screenshots/2026-01-25-mainmenu.png` - Includes date if needed - ❌ `screenshots/screenshot.png` - Too generic - ❌ `screenshots/test.png` - Not descriptive **Recommended patterns:** - `screenshots/{feature}-{state}.png` - e.g., `mainmenu-default.png` - `screenshots/{feature}-{test-context}.png` - e.g., `timer-test-5seconds.png` - `screenshots/{validation-type}-{scene}.png` - e.g., `ui-validation-mainmenu.png` ## Migration **When discovering screenshots in project root, move them to `screenshots/` folder:** ### Manual Migration ```bash # Create screenshots folder mkdir -p screenshots/ # Move existing screenshots from root to screenshots/ mv *.png screenshots/ 2>/dev/null || true # Or move specific files mv mainmenu-verification.png screenshots/ mv timer-test.png screenshots/ ``` ### Automated Migration Script ```bash #!/bin/bash # migrate-screenshots.sh # Create screenshots folder mkdir -p screenshots/ # Find PNG files in project root (excluding node_modules, .git, etc.) find . -maxdepth 1 -name "*.png" -type f ! -path "./node_modules/*" ! -path "./.git/*" -exec mv {} screenshots/ \; echo "Screenshots migrated to screenshots/ folder" ``` ### Verification **After migration, verify screenshots are in the correct location:** ```bash # List screenshots in screenshots/ folder ls -la screenshots/ # Verify no PNG files remain in project root (excluding node_modules, .git, etc.) find . -maxdepth 1 -name "*.png" -type f ! -path "./node_modules/*" ! -path "./.git/*" ``` ## Troubleshooting ### Screenshots Ended Up in Wrong Location **If you discover screenshots in the project root instead of `screenshots/` folder:** 1. **Verify the issue:** ```bash # Check for PNG files in project root find . -maxdepth 1 -name "*.png" -type f ``` 2. **Create screenshots folder if missing:** ```bash mkdir -p screenshots/ ``` 3. **Move misplaced screenshots:** ```bash # Move all PNG files from root to screenshots/ mv *.png screenshots/ 2>/dev/null || true # Or move specific files mv mainmenu-verification.png screenshots/ mv timer-test.png screenshots/ ``` 4. **Verify migration:** ```bash # List screenshots in correct location ls -la screenshots/ # Verify no PNG files remain in project root find . -maxdepth 1 -name "*.png" -type f ``` 5. **Prevent future issues:** - Always run `mkdir -p screenshots/` before capturing screenshots - Always include `screenshots/` in the screenshot path - Review this skill's instructions before capturing screenshots ### Common Mistakes **Mistake 1: Forgetting to create folder** ```bash # ❌ WRONG - Folder doesn't exist, screenshot may fail or save to root agent-browser screenshot screenshots/test.png # ✅ CORRECT - Create folder first mkdir -p screenshots/ agent-browser screenshot screenshots/test.png ``` **Mistake 2: Missing screenshots/ in path** ```bash # ❌ WRONG - Path doesn't include screenshots/ agent-browser screenshot test.png # ✅ CORRECT - Path includes screenshots/ agent-browser screenshot screenshots/test.png ``` **Mistake 3: Using relative path without screenshots/** ```bash # ❌ WRONG - Relative path without folder page.screenshot({ path: 'verification.png' }) # ✅ CORRECT - Path includes screenshots/ page.screenshot({ path: 'screenshots/verification.png' }) ``` ## Screenshot Freshness Verification ### Verify Screenshots Are Current **Always verify screenshots are current before using them for verification:** ```bash # Force browser refresh before capturing verification screenshots agent-browser reload agent-browser wait 2000 # Wait for reload # Then capture screenshot agent-browser screenshot screenshots/verification.png ``` ### Timestamp Verification Techniques **Pattern 1: Check File Timestamp** ```bash # Check screenshot file timestamp ls -l screenshots/verification.png # Verify file was created recently (within last 10 seconds) file_age=$(($(date +%s) - $(stat -f %m screenshots/verification.png))) if [ $file_age -lt 10 ]; then echo "Screenshot is fresh" else echo "Screenshot may be stale" fi ``` **Pattern 2: Timestamp in Filename** ```bash # Include timestamp in filename timestamp=$(date +%Y%m%d_%H%M%S) agent-browser screenshot "screenshots/verification-${timestamp}.png" ``` **Pattern 3: Browser State Verification** ```bash # Verify browser state before screenshot agent-browser eval " const state = { url: window.location.href, timestamp: Date.now(), testSeamReady: window.__TEST__?.ready || false }; JSON.stringify(state) " # Capture screenshot agent-browser screenshot screenshots/verification.png ``` ### Detecting Stale Screenshots **Check for stale screenshots:** ```bash # Check if screenshot exists and is recent check_screenshot_freshness() { local screenshot=$1 local max_age=30 # 30 seconds max age if [ ! -f "$screenshot" ]; then echo "Screenshot not found" return 1 fi local file_age=$(($(date +%s) - $(stat -f %m "$screenshot"))) if [ $file_age -gt $max_age ]; then echo "Screenshot is stale (${file_age}s old)" return 1 fi echo "Screenshot is fresh" return 0 } ``` ### Force Browser Refresh Before Capture **Always refresh browser before capturing verification screenshots:** ```bash # Force refresh before screenshot agent-browser reload agent-browser wait 2000 # Wait for reload # Verify HMR has applied changes (if applicable) agent-browser eval " const lastReload = window.__HMR_LAST_RELOAD__ || 0; const now = Date.now(); const timeSinceReload = now - lastReload; timeSinceReload < 5000 ? 'Recently reloaded' : 'Stale state' " # Then capture screenshot agent-browser screenshot screenshots/verification.png ``` ## Timing Considerations ### When to Wait for Scene Transitions/Updates **Wait for scene transitions before capturing:** ```bash # Navigate to scene agent-browser eval "window.__TEST__.commands.goToScene('GameScene')" # Wait for transition (don't capture immediately) agent-browser wait 500 # Wait for scene transition # Wait for scene initialization agent-browser eval " new Promise((resolve) => { const check = () => { if (window.__TEST__?.ready) { resolve(true); } else { setTimeout(check, 100); } }; check(); }) " # Now capture screenshot agent-browser screenshot screenshots/gamescene-ready.png ``` ### Verify HMR Has Applied Changes Before Screenshots **Always verify HMR has applied changes before capturing:** ```bash # Make code change (outside browser) # Wait for HMR to apply agent-browser eval " const lastReload = window.__HMR_LAST_RELOAD__ || 0; const now = Date.now();