qt-testing

name

qt-testing

description

Capture and visually inspect FreeCCR's PySide6/Qt GUI widgets using screenshots. Use when asked to verify GUI rendering, test widget appearance, check layouts, theming/QSS, or visually inspect any FreeCCR widget (image preview, sliders panel, curve editor, thumbnail list, dust panel, export dialog, main window). Enables Claude to "see" the Qt interface by capturing offscreen screenshots and analyzing them with vision.

Qt GUI Testing (FreeCCR)

Capture screenshots of FreeCCR's Qt widgets for visual inspection without displaying windows on screen, then read the image back and critique it.

Quick Start

# Capture any widget
import sys
sys.path.insert(0, ".claude/skills/qt-testing")   # so `from scripts.qt_capture import ...` works
from scripts.qt_capture import capture_widget, init_qt, setup_freeccr_path

setup_freeccr_path()          # puts repo root + src/ on sys.path
app = init_qt()               # creates the QApplication

path = capture_widget(my_widget, "description_here")
# Then read the screenshot with the Read tool

Core Script

Run scripts/qt_capture.py or import helpers from it:

# Standalone self-test (renders a throwaway widget, saves a PNG)
python .claude/skills/qt-testing/scripts/qt_capture.py

Helpers exposed by scripts/qt_capture.py:

• setup_freeccr_path() — add the repo root and src/ to sys.path (call before importing FreeCCR modules).
• init_qt(offscreen=False) — create/return the QApplication. Pass offscreen=True to force the offscreen Qt platform (matches FreeCCR's headless tests); the default Windows platform also works.
• capture_widget(widget, "desc") — render offscreen and save a PNG, returns the path.
• capture_and_click(widget, x, y, "desc") — click the child at (x, y), then capture.

Output Location

All screenshots save to: <repo>/scratch/.qt-screenshots/ (git-ignored).

Naming: {YYYY-MM-DD.HH-MM-SS}_{description}.png

Workflow

1. Create/obtain the FreeCCR widget to test (see examples below)
2. Call capture_widget(widget, "description")
3. Read the saved screenshot with the Read tool
4. Analyze with vision to verify correctness (layout, spacing, theming, labels)

FreeCCR Widget Cheat-Sheet

Import after setup_freeccr_path(). None require images loaded; the ccr_backend singleton is created on import.

from core.ccr_backend import ccr_backend          # ensures the global singleton exists

from ui.main_window import MainWindow              # MainWindow()              — full app shell
from widgets.sliders_panel import SlidersPanel     # SlidersPanel(None)        — Kelvin/tint/exposure controls
from widgets.image_preview import ImagePreview     # ImagePreview(None)        — central canvas + toolbar
from widgets.curve_editor import CurveEditor       # CurveEditor(None)         — tone curve tool
from widgets.thumbnail_list import ThumbnailList   # ThumbnailList(lambda *a: None)  — sidebar (needs a callback)
from widgets.tether_banner import TetherBanner     # TetherBanner(None)        — tether status strip

# Widgets that need collaborators — pass lightweight stubs:
from widgets.dust_panel import DustRemovalPanel    # DustRemovalPanel(main_window, image_preview)
from widgets.export_dialog import ExportSettingsDialog  # ExportSettingsDialog()  — reads ccr_backend.images

Example: Capture the sliders panel

import sys
sys.path.insert(0, ".claude/skills/qt-testing")
from scripts.qt_capture import capture_widget, init_qt, setup_freeccr_path

setup_freeccr_path()
app = init_qt()

from core.ccr_backend import ccr_backend           # singleton ready
from widgets.sliders_panel import SlidersPanel

panel = SlidersPanel(None)
panel.resize(360, 700)                              # give it a sensible size before grab()
path = capture_widget(panel, "sliders_panel_default")
print(f"Inspect: {path}")

Example: Capture the full main window

import sys
sys.path.insert(0, ".claude/skills/qt-testing")
from scripts.qt_capture import capture_widget, init_qt, setup_freeccr_path

setup_freeccr_path()
app = init_qt()

from ui.main_window import MainWindow

win = MainWindow()
win.resize(1280, 800)
path = capture_widget(win, "main_window_empty")
win.close()
print(f"Inspect: {path}")

Interaction Pattern

To interact with widgets (click buttons, etc.):

# Find widget at coordinates (from vision analysis)
target = widget.childAt(x, y)

# Trigger it directly (not mouse events)
if hasattr(target, 'click'):
    target.click()
    QApplication.processEvents()

# Capture result
capture_widget(widget, "after_click")

Key Points

• Uses Qt.WA_DontShowOnScreen - no window popup.
• Renders identically to on-screen display (verified upstream).
• Call setup_freeccr_path() before importing FreeCCR modules; import ccr_backend first so the singleton exists.
• Give widgets a size (resize/setFixedSize) before grab() — an unsized widget may render at its minimum.
• Call processEvents() after interactions before capture.
• Use childAt(x, y) to map vision coordinates to widgets.
• Direct method calls (.click()) work; simulated mouse events don't.
• DustRemovalPanel requires a main_window and image_preview; pass real instances or minimal stubs exposing the attributes it reads.