Screenshot Testing

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 default_save_dir
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 {save_dir}/YYYY-MM-DD/YYYYMMDD_HHMMSS.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 screenshot_screen with specific display_id
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 list_windows before screenshot_window 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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.