Skip to content

browser.md

Latest commit

 

History

History
235 lines (166 loc) · 5.25 KB

browser.md

File metadata and controls

235 lines (166 loc) · 5.25 KB

CLI Browser Feature

Quick browser screenshots with one command.

Overview

The -b flag (or co browser) takes instant screenshots without writing code. Perfect for debugging, testing, and sharing visual proof.

Basic Usage

co -b "screenshot localhost:3000"

Saves to .tmp/screenshot_YYYYMMDD_HHMMSS.png by default.

Command Format

co -b "screenshot [URL] [save to PATH] [size SIZE]"

All parts except URL are optional.

Examples

Basic Screenshot

# Screenshot local development
co -b "screenshot localhost:3000"

# With specific port
co -b "screenshot localhost:8080"

# External site
co -b "screenshot example.com"

Save to Specific Path

# Save to temp directory
co -b "screenshot localhost:3000 save to /tmp/debug.png"

# Save to current directory with name
co -b "screenshot localhost:3000 save to homepage.png"

# Save to subdirectory
co -b "screenshot localhost:3000 save to screenshots/test.png"

Device Sizes

# iPhone viewport
co -b "screenshot localhost:3000 size iphone"

# Custom dimensions
co -b "screenshot localhost:3000 size 390x844"

# Common presets
co -b "screenshot localhost:3000 size ipad"
co -b "screenshot localhost:3000 size desktop"

Complete Examples

# Debug mobile checkout flow
co -b "screenshot localhost:3000/checkout save to /tmp/checkout-mobile.png size iphone"

# Document bug on specific page
co -b "screenshot localhost:3000/xray save to bug-report.png size 1920x1080"

# Test responsive design
co -b "screenshot localhost:3000 save to mobile.png size 390x844"
co -b "screenshot localhost:3000 save to tablet.png size 768x1024"
co -b "screenshot localhost:3000 save to desktop.png size 1920x1080"

Device Presets

Preset Dimensions Device
iphone 390x844 iPhone 14/15
android 360x800 Common Android
ipad 768x1024 iPad
desktop 1920x1080 Full HD Desktop

URL Handling

The command intelligently handles URLs:

  • localhost → http://localhost
  • localhost:3000 → http://localhost:3000
  • example.com → https://example.com
  • http://example.com → http://example.com (unchanged)

Output Files

If no path specified:

  • Saves under .tmp/
  • Named screenshot_YYYYMMDD_HHMMSS.png
  • Example: .tmp/screenshot_20240115_143022.png

Installation

Browser features require Playwright:

pip install playwright
playwright install chromium

Or install ConnectOnion with browser support:

pip install connectonion[browser]

Use Cases

1. Debug Local Development

# Quick check of homepage
co -b "screenshot localhost:3000"

# Debug specific route
co -b "screenshot localhost:3000/api/status"

2. Document Bugs

# Capture error state
co -b "screenshot localhost:3000/error save to bug.png"

# Mobile-specific issue
co -b "screenshot localhost:3000/mobile-bug save to mobile-issue.png size iphone"

3. Test Responsive Design

# Test different viewports
for size in iphone android ipad desktop; do
  co -b "screenshot localhost:3000 save to view-$size.png size $size"
done

4. CI/CD Integration

# In GitHub Actions or similar
co -b "screenshot $DEPLOY_URL save to artifacts/deployed.png"

Error Messages

# Missing URL
co -b "screenshot"
❌ Usage: co -b "screenshot [URL] [save to PATH] [size SIZE]"

# Playwright not installed  
co -b "screenshot localhost:3000"
❌ Browser tools not installed
   Run: pip install playwright && playwright install chromium

# Missing OPENAI_API_KEY
co -b "screenshot localhost:3000"
❌ Natural language browser agent unavailable. Set OPENAI_API_KEY and try again.

# Cannot reach URL
co -b "screenshot localhost:3000"
❌ Cannot reach http://localhost:3000
   Is your server running?

# Permission denied
co -b "screenshot localhost:3000 save to /root/test.png"
❌ Cannot save to /root/test.png (permission denied)

Tips

  1. Quick Debug: Just co -b "screenshot localhost:3000" for instant feedback
  2. Organize Screenshots: Use descriptive paths like save to bugs/issue-123.png
  3. Test Viewports: Use device names (iphone, ipad) for common sizes
  4. Timestamps: Default filenames include timestamp for versioning

Limitations

  • Screenshots only (no interaction, clicking, forms)
  • Single page at a time
  • Headless browser only
  • PNG format only

For complex browser automation, use the full ConnectOnion browser agent or Playwright directly.

Requirements

  • OPENAI_API_KEY must be set (managed keys are not used here)
  • Playwright installed and set up

Examples for Common Frameworks

Next.js

co -b "screenshot localhost:3000"
co -b "screenshot localhost:3000/_error save to error.png"

FastAPI

co -b "screenshot localhost:8000"
co -b "screenshot localhost:8000/docs save to api-docs.png"

Django

co -b "screenshot localhost:8000"
co -b "screenshot localhost:8000/admin save to admin.png"

React Dev Server

co -b "screenshot localhost:3000"
co -b "screenshot localhost:3000 size iphone"

Summary

The -b flag provides dead-simple browser screenshots. No setup, no complexity - just describe what screenshot you want and where to save it. Perfect for debugging during development.