Visual Testing

Take screenshots of the running app to verify UI changes visually.

When to Use This Skill

Use this skill when:

• Verifying visual changes to demo/showcase pages
• Capturing screenshots for UI review
• Debugging layout or styling issues
• Testing demo component interactions
• Checking cursor alignment in interactive demos

Quick Start

# Check dev server status
./.claude/skills/visual-testing/scripts/visual-test.sh status

# Start dev server if needed
./.claude/skills/visual-testing/scripts/visual-test.sh start

# Screenshot a demo slide with debug markers
./.claude/skills/visual-testing/scripts/visual-test.sh demo cast-assignment --debug

# View the screenshot (Claude can read images)
# Path: /tmp/ballee-screenshots/demo-cast-assignment-TIMESTAMP.png

Commands

Command	Description
status	Check if dev server is running on port 3012
start	Start dev server in background
stop	Stop dev server
screenshot <url>	Take screenshot of any URL
demo [slide-id]	Screenshot demo showcase (optional slide)
demo-all	Screenshot all demo slides
list-slides	List available demo slide IDs

Options

Option	Description	Default
--debug	Add ?debug=true to URL (shows target markers)	false
--viewport WxH	Set viewport dimensions	1200x900
--name <name>	Custom screenshot filename	auto-generated
--full-page	Capture full scrollable height	false
--wait <ms>	Extra wait time after page load	2000

Demo Slide IDs

ID	Interactive Demo
cast-assignment	CastAssignmentDemo
contract-acceptance	ContractAcceptanceDemo
event-creation	EventCreationDemo
hire-order-view	HireOrderViewDemo
invoice-download	InvoiceDownloadDemo
invoice-validate	InvoiceValidateDemo
reimbursement-upload	ReimbursementUploadDemo

Screenshot Output

Screenshots are saved to: /tmp/ballee-screenshots/

Naming pattern:

• Demo: demo-{slide-id}-{timestamp}.png
• Custom: {custom-name}.png
• URL: screenshot-{timestamp}.png

Example Workflows

Verify Demo After Coordinate Changes

# 1. Ensure server is running
./.claude/skills/visual-testing/scripts/visual-test.sh status

# 2. Screenshot the changed slide with debug markers
./.claude/skills/visual-testing/scripts/visual-test.sh demo cast-assignment --debug

# 3. Read the screenshot to verify cursor alignment
# Use Claude's Read tool on /tmp/ballee-screenshots/demo-cast-assignment-*.png

Capture All Demo States

# Screenshot all demo slides for full review
./.claude/skills/visual-testing/scripts/visual-test.sh demo-all --debug

# Screenshots saved to /tmp/ballee-screenshots/

Custom Page Screenshot

# Screenshot any page
./.claude/skills/visual-testing/scripts/visual-test.sh screenshot \
  http://localhost:3012/admin/events \
  --name "admin-events" \
  --viewport 1920x1080

Troubleshooting

"Dev server not running"

Start the dev server:

./.claude/skills/visual-testing/scripts/visual-test.sh start
# Or manually: pnpm dev

"Screenshot timeout"

• Check the URL is correct
• Ensure dev server is responding: curl http://localhost:3012
• Try increasing wait time: --wait 5000

"Puppeteer not found"

Puppeteer should be installed. If not:

cd apps/web && pnpm add -D puppeteer

Related Files

• Demo showcase: apps/web/app/demo/fever/showcase/page.tsx
• Demo components: apps/web/components/demo/interactive/demos/
• Interactive demo wrapper: apps/web/components/demo/interactive/interactive-demo.tsx