browser-testing-with-screenshots

name browser-testing-with-screenshots description Use when testing web applications with visual verification - automates Chrome browser interactions, element selection, and screenshot capture for confirming UI functionality Browser Testing with Screenshots Overview Automate Chrome browser testing with visual verification using browser-tools. Connect to Chrome DevTools Protocol for navigation, interaction, and screenshot capture to confirm application functionality. Prerequisites REQUIRED: Install agent-tools from https://github.com/badlogic/agent-tools # Clone and install agent-tools git clone https://github.com/badlogic/agent-tools.git cd agent-tools # Follow installation instructions in the repository # Ensure all executables (browser-start.js, browser-nav.js, etc.) are in your PATH Verify installation: # Check that browser tools are available which browser-start.js which browser-nav.js which browser-screenshot.js All browser-* commands referenced in this skill come from the agent-tools repository and must be properly installed and accessible in your system PATH. When to Use Use this skill when: Testing web application UI flows Verifying visual changes or layouts Automating repetitive browser interactions Documenting application behavior with screenshots Testing localhost applications during development Need to interact with elements that require human-like selection Don't use for: API testing (use direct HTTP calls) Headless testing where visuals don't matter Simple page content validation (use curl/wget) Quick Reference Task Command Purpose Start browser browser-start.js Launch Chrome with debugging Navigate browser-nav.js http://localhost:5172/dashboard Go to specific URL Take screenshot browser-screenshot.js Capture current viewport Pick elements browser-pick.js "Select the login button" Interactive element selection Run JavaScript browser-eval.js 'document.title' Execute code in page context Extract content browser-content.js Get readable page content View cookies browser-cookies.js List session cookies Setup and Basic Workflow 1. Start Chrome with Remote Debugging # Launch Chrome with debugging enabled (preserves user profile) browser-start.js # Or start fresh (no cookies, clean state) browser-start.js --fresh Expected Result : Chrome opens on port 9222 with DevTools Protocol enabled 2. Navigate to Application # Go to your application starting point browser-nav.js http://localhost:5172/dashboard Verify : Browser navigates to dashboard page 3. Capture Baseline Screenshot # Take initial screenshot to confirm page loaded browser-screenshot.js Output : Returns path to screenshot file (e.g., screenshot_20231203_141532.png ) Testing Workflow with Screenshots Complete Test Scenario Example #!/bin/bash # Test login and dashboard functionality echo "🚀 Starting browser test..." # 1. Launch browser browser-start.js --fresh # 2. Navigate to login page browser-nav.js http://localhost:5172/login sleep 2 # 3. Take screenshot of login page LOGIN_SHOT=$(browser-screenshot.js) echo "📸 Login page: $LOGIN_SHOT " # 4. Fill login form (interactive element picking) browser-pick.js "Click the username field" browser-eval.js 'document.activeElement.value = "testuser"' browser-pick.js "Click the password field" browser-eval.js 'document.activeElement.value = "password123"' # 5. Screenshot filled form FORM_SHOT=$(browser-screenshot.js) echo "📸 Filled form: $FORM_SHOT " # 6. Submit form browser-pick.js "Click the login button" sleep 3 # 7. Verify dashboard loaded browser-nav.js http://localhost:5172/dashboard DASHBOARD_SHOT=$(browser-screenshot.js) echo "📸 Dashboard: $DASHBOARD_SHOT " # 8. Verify specific dashboard elements browser-pick.js "Select the navigation menu" browser-eval.js 'console.log("Navigation found:", !!document.querySelector(".nav"))' echo "✅ Test complete. Screenshots saved." Element Interaction Pattern # Interactive element selection (best for dynamic content) browser-pick.js "Select the submit button" # User clicks element in browser → returns CSS selector # Use returned selector for automation SELECTOR=$(browser-pick.js "Select the submit button" | grep "selector:" ) browser-eval.js "document.querySelector(' $SELECTOR ').click()" # Take screenshot to verify action browser-screenshot.js Advanced Usage JavaScript Evaluation for Complex Interactions # Check if element exists before interaction browser-eval.js 'document.querySelector("#login-form") !== null' # Wait for dynamic content browser-eval.js ' new Promise(resolve => { const check = () => { if (document.querySelector(".loaded")) resolve(true); else setTimeout(check, 100); }; check(); }) ' # Extract form data browser-eval.js 'JSON.stringify(Object.fromEntries(new FormData(document.querySelector("form"))))' Screenshot with Timing # Navigate and wait before screenshot browser-nav.js http://localhost:5172/slow-page sleep 5 # Wait for animations/loading browser-screenshot.js Content Extraction for Verification # Get page title PAGE_TITLE=$(browser-eval.js 'document.title' ) echo "Current page: $PAGE_TITLE " # Extract readable content browser-content.js > page_content.md # Check for specific text browser-eval.js 'document.body.textContent.includes("Welcome to Dashboard")' Common Mistakes Mistake Problem Solution No sleep after navigation Screenshots of loading page Add sleep 2-5 after nav Hardcoded selectors Breaks when UI changes Use browser-pick.js for selection Missing Chrome setup "Connection refused" errors Run browser-start.js first Wrong localhost port Navigation fails Verify application is running on correct port Screenshot timing Captures before content loads Wait for page load or specific elements Not preserving state Login lost between commands Use default profile, not --fresh Error Handling # Check if Chrome is running if ! browser-eval.js 'true' 2>/dev/null; then echo "❌ Chrome not connected. Running browser-start.js..." browser-start.js fi # Verify navigation succeeded if browser-eval.js 'location.href.includes("dashboard")' ; then echo "✅ Navigation successful" else echo "❌ Navigation failed" exit 1 fi File Output Patterns Screenshots : screenshot_YYYYMMDD_HHMMSS.png in current directory Content : Markdown format via stdout from browser-content.js Selectors : CSS selectors from browser-pick.js interaction JavaScript results : JSON or string values from browser-eval.js Integration with Testing Frameworks # Create test evidence directory mkdir -p test-results/$( date +%Y%m%d_%H%M%S) cd test-results/$( date +%Y%m%d_%H%M%S) # Run tests with organized screenshots browser-start.js for page in login dashboard profile; do browser-nav.js "http://localhost:5172/ $page " sleep 2 screenshot=$(browser-screenshot.js) mv " $screenshot " " ${page} _page.png" echo "✅ $page page tested" done Real-World Impact Benefits: Visual verification : Screenshots provide immediate feedback on UI state Interactive debugging : Element picker works with dynamic/complex selectors State preservation : Maintains login sessions between commands Evidence collection : Automated screenshot capture for test documentation Development workflow : Quick verification of localhost changes Results: Faster UI testing iteration (visual confirmation vs manual checking) Reliable element selection (human picks, automation uses) Test documentation with visual proof Catches visual regressions immediately Key principle: Combine automated navigation with human element selection for robust, maintainable browser testing.