📦

Overview

gpyqt-instrument connects Claude Code to running PyQt applications for automated testing, instrumentation, and UI interaction. No more manual clicking to verify UI changes.

Key Features

  • Live Connection - Connect to running PyQt apps via MCP
  • Widget Tree Snapshots - Get structured view of entire UI hierarchy
  • Automated Interactions - Click, type, select, scroll programmatically
  • Screenshot Comparison - Baseline vs. actual visual regression testing
  • Mutation Testing - Verify UI behavior under edge cases
  • Flakiness Analysis - Identify unreliable test patterns

Installation

# Install via pip
pip install gpyqt-instrument

# Or add as MCP server to Claude Code
claude code mcp add gpyqt-instrument

Quick Start

# Connect to running PyQt app
mcp__gpyqt-instrument__qt_connect()

# Capture widget tree snapshot
mcp__gpyqt-instrument__qt_snapshot()

# Click a button
mcp__gpyqt-instrument__qt_click(ref="MainWindow/QPushButton[0]")

# Take screenshot
mcp__gpyqt-instrument__qt_capture_screenshot(name="login-page")

# Compare with baseline
mcp__gpyqt-instrument__qt_compare_screenshot(
    baseline="login-page-baseline.png",
    current="login-page.png"
)

Use Cases

UI Regression Testing

Automatically capture and compare UI state across code changes. Catch visual regressions before they ship.

End-to-End Workflow Testing

Script complete user workflows: login, navigate, interact, verify results. Run automatically on every commit.

UI State Debugging

Inspect widget properties, parent-child relationships, and signals at runtime without stopping the application.

Mutation Testing

Automatically inject edge-case inputs and verify UI handles them gracefully. Find crashes before users do.

Architecture

gpyqt-instrument uses Qt’s introspection APIs to connect to running applications. It communicates via:

  • MCP Protocol for Claude Code integration
  • Qt Signals/Slots for event monitoring
  • QPixmap for screenshot capture
  • SQLite for test history and baselines

Perfect For

  • PyQt6 application developers
  • QA teams testing desktop applications
  • Developers using Claude Code for UI development
  • Teams transitioning from manual to automated UI testing

Best Practices

  1. Run tests in isolated environment - Use virtual displays (Xvfb) for headless CI
  2. Store baselines in version control - Track expected UI state alongside code
  3. Name snapshots meaningfully - “login-success”, “error-dialog” not “test1”, “test2”
  4. Test both golden path and edge cases - Happy path + error conditions

Documentation

Support