peekaboo

Peekaboo Visual Testing

Peekaboo is a macOS automation tool for high-fidelity screen capture, AI analysis, and GUI automation. Use it to test macOS app UIs, verify visual elements, and automate interactions.

Help Discovery (Use CLI Help for Current Options)

Peekaboo CLI is self-documenting. Always discover current commands and flags via help - this prevents outdated assumptions:

peekaboo --help                    # All commands
peekaboo <command> --help          # Command options
peekaboo <command> <sub> --help    # Subcommand options

Key Help Categories

Category	Help Command	Use For
Vision	peekaboo see --help	Capture UI state, get element IDs
Capture	peekaboo image --help	Save screenshots
Click	peekaboo click --help	Click elements
Type	peekaboo type --help	Send text input
Keys	peekaboo press --help, peekaboo hotkey --help	Keyboard navigation
App	peekaboo app --help	Switch, launch, quit apps
Window	peekaboo window --help	Focus, list windows
Daemon	peekaboo daemon --help	Headless mode

The Correct Targeting Pattern (Critical!)

WRONG patterns that cause errors:

# WRONG - click with --app causes bridge errors
peekaboo see --app "MyApp"
peekaboo click --app "MyApp" --on elem_5     # Bridge error!

# WRONG - click without snapshot targets FRONTMOST window, not your app
peekaboo see --app "MyApp"
peekaboo click --on elem_5                    # Clicks wrong window!

CORRECT pattern: switch -> see -> click with snapshot

# 1. Switch to app (brings it to front)
peekaboo app switch --to "MyApp"

# 2. Capture UI and get snapshot_id
SNAPSHOT=$(peekaboo see --app "MyApp" --json | jq -r '.data.snapshot_id')

# 3. Click using ONLY --snapshot (no --app flag)
peekaboo click --snapshot "$SNAPSHOT" --on elem_5

Why this works:

• app switch brings the target window to front
• see --app captures that specific app's UI, returns snapshot_id
• The snapshot contains: app context, window info, element positions
• click --snapshot uses the snapshot context - do not add --app

Core Workflow: See -> Interact -> Verify

1. See: Capture UI State

peekaboo app switch --to "MyApp"
peekaboo see --app "MyApp" --json > ui.json
# Extract snapshot_id for subsequent commands
SNAPSHOT=$(jq -r '.data.snapshot_id' ui.json)

2. Interact: Click, Type, or Navigate

# Click by element ID
peekaboo click --snapshot "$SNAPSHOT" --on elem_3

# Type text
peekaboo type --snapshot "$SNAPSHOT" "hello world"

# Keyboard navigation (often more reliable)
peekaboo press down down return
peekaboo hotkey cmd,s

3. Verify: Re-capture and Compare

peekaboo see --app "MyApp" --json > ui_after.json
# Compare element counts, labels, check for expected changes

Element Targeting Options

Check peekaboo click --help for current options. Common patterns:

Method	Syntax	When to Use
Element ID	--on elem_12	Most reliable when IDs are stable
Fuzzy query	"Submit"	When label text is unique
Coordinates	--coords 100,200	Fallback, no snapshot needed

Important: Element IDs are snapshot-specific. elem_12 from one see command is NOT the same as elem_12 from another capture.

Debugging Apps (Debug Builds Without Bundle IDs)

Debug builds and unsigned apps often lack bundle IDs, causing click targeting to fail or hit the wrong app.

Option 1: Target by PID

PID=$(pgrep -x "MyDebugApp")
peekaboo app switch --to "PID:$PID"
peekaboo see --app "PID:$PID" --json

Option 2: Keyboard Navigation (Often More Reliable)

peekaboo app switch --to "MyDebugApp"
peekaboo press down down down return    # Arrow keys + Return
peekaboo hotkey cmd,shift,o              # Keyboard shortcuts
peekaboo type "search text" --return     # Type + Enter

When to Use Keyboard Over Clicks

• Debug builds without bundle IDs
• List/tree navigation (arrow keys work better)
• Form fields (Tab between, Return to submit)
• Unstable element IDs that change between captures

Keyboard Commands Reference

peekaboo press tab tab return           # Tab navigation + activate
peekaboo press down down down return    # Arrow navigation + activate
peekaboo press up                       # Single arrow key
peekaboo hotkey cmd,a                   # Select all
peekaboo hotkey cmd,c                   # Copy
peekaboo hotkey cmd,v                   # Paste
peekaboo type "text" --return           # Type then press Enter
peekaboo type "text" --tab 2            # Type then press Tab twice

Headless Mode Basics

For CI/CD or background automation:

# Start daemon
peekaboo daemon start
peekaboo daemon status

# MCP mode auto-starts daemon
peekaboo mcp

For detailed headless setup, environment variables, and CI/CD integration: See references/headless-automation.md

Permissions Checklist

Peekaboo requires macOS permissions:

• Screen Recording: System Settings > Privacy > Screen Recording
• Accessibility: System Settings > Privacy > Accessibility

Check status:

peekaboo permissions status

Error Recovery

Error	Solution
SNAPSHOT_NOT_FOUND	Re-run peekaboo see to get fresh snapshot
Element not found	Check element IDs with see --json, verify UI hasn't changed
Bridge error	Check peekaboo bridge status, ensure Peekaboo.app is running
Focus issues	Use peekaboo app switch before capture
Click going to wrong app	Use PID targeting or keyboard navigation
Timeout	Increase --focus-timeout or add waits between commands

When to Read Reference Files

Need	Reference File
Complex testing patterns, multi-step sequences	references/visual-testing-patterns.md
CI/CD and daemon setup, environment variables	references/headless-automation.md
Debugging errors, Space switching issues	references/troubleshooting.md