Screenshot Testing

A guide for conducting effective UI testing using screenshots. This skill covers the screenshot-mcp tools, testing workflows, and comparison strategies for native application testing.

Configuration

Check for plugin settings at .claude/screenshot.local.md before taking screenshots.

Settings file format:

---
default_save_dir: /path/to/screenshots
---

When settings file exists:

1. Read the file using the Read tool
2. Parse YAML frontmatter to extract defaultsavedir
3. Use this path as save_dir when user wants to save screenshots
4. If user specifies a different path, use their path instead

When settings file does not exist:

• Ask user if they want screenshots saved
• If yes, ask for save location or suggest creating settings file

Available MCP Tools

The screenshot MCP server provides 5 tools:

Testing Workflow

Step 1: Identify Target Window

Before capturing, identify the correct window:

1. Call list_windows to get all visible windows
2. Find target by app name or title
3. Note the window ID for screenshot_window

Window matching strategies:

• By app name: Look for app field (e.g., "Electron", "Simulator")
• By title: Use window_title parameter for fuzzy matching
• By bounds: Check bounds to identify window by size/position

Step 2: Capture Screenshot

Choose the appropriate capture method:

• Single window: Use screenshot_window with window ID or title
• Full screen: Use screenshot_screen for entire display
• Specific area: Use screenshot_region for precise coordinates

Step 3: Analyze Results

After capturing, analyze the screenshot for:

• Layout correctness (element positions, spacing)
• Visual elements (colors, fonts, icons)
• Content accuracy (text, data display)
• Responsive behavior (proper sizing)

Comparison Testing

For detecting UI changes between versions:

Baseline Workflow

1. Create baseline: Capture screenshots with save_dir parameter
2. Store organized: Screenshots save as {savedir}/YYYY-MM-DD/YYYYMMDDHHMMSS.png
3. Compare later: Capture new screenshots and compare visually

Visual Comparison Approach

When comparing screenshots:

1. Capture current state screenshot
2. Load baseline screenshot from saved location
3. Compare visually for differences:

- Layout shifts - Missing/extra elements - Color or style changes - Text content differences

Report findings with specific observations about what changed.

Multi-Display Testing

For applications spanning multiple monitors:

1. Call list_displays to see all available displays
2. Note display IDs and bounds for positioning context
3. Use screenshotscreen with specific displayid
4. Consider window positions relative to display bounds

Platform Support

On macOS, grant Screen Recording permission in System Settings > Privacy & Security > Screen Recording.

Best Practices

Window Identification

• Always call listwindows before screenshotwindow to get fresh window IDs
• Window IDs can change when windows close/reopen
• Use window_title for more stable identification

Screenshot Organization

• Use save_dir parameter for regression testing
• Screenshots auto-organize by date
• Keep baseline screenshots in version control

Testing Strategy

• Capture at consistent window sizes for comparison
• Test on single display first, then multi-display
• Document expected visual state before testing

Additional Resources

Examples

For practical testing examples, see:

• examples/electron-app-testing.md - Testing an Electron application login flow

Reference Files

For detailed patterns:

• references/testing-patterns.md - Common UI testing patterns and strategies