verify-qt-ui

# Verify Qt UI For a change that affects visible UI, inspect the actual rendered result before claiming it looks correct. Combine that inspection with behavioral regressions. Generating an image or passing geometry assertions is not visual inspection. This skill is self-contained. It requires no particular repository structure, font asset, test framework, helper module, or other skill. Adapt the Qt API calls to the project's language, binding, and supported Qt version. ## Discover the project's verification setup - Read available project guidance and trace the affected widgets and callers. Identify the application entry point, styles and palettes, font selection, supported platforms and languages, and existing tests or preview tools. - Reuse a suitable existing environment and isolated test harness when available. Inspect what it actually initializes: application objects, fonts, settings, fixtures, and event handling. Do not assume a helper provides these guarantees from its name alone, or require a project to adopt a particular helper API. - If no suitable harness exists, build the smallest temporary preview around the real widget, with representative data and substitutes for external effects. Own one QApplication in the process, initialize only necessary dependencies, isolate settings and storage before application imports that may access them, and avoid starting the normal application against the user's configuration. - Find the project's test commands and relevant coverage. If none exist, use a focused executable check and visual inspection; report the coverage gap rather than inventing a test-suite pass. Add durable test infrastructure only when the requested change warrants it. ## Choose evidence for the change - Reproduce the reported appearance or interaction with representative data. For a visual defect, inspect the before state when practical, then inspect the final implementation in the same conditions. Do not change the UI merely to satisfy a test whose fonts, style, or assumptions do not represent the product. - Render the actual application widgets with their intended style and palette. Select the affected supported languages, themes, window sizes, and scale factors. Include long translations and different writing systems or text directions when the application supports them. Exercise realistic input values, placeholders, and implicated enabled/disabled or error states. Do not expand every small fix into a whole-application audit. - For focus, menus, keyboard navigation, accessibility, window placement, or platform integration, exercise the relevant interaction as well as appearance. A screenshot cannot prove event delivery or native behavior. ## Account for the three desktop platforms Record Windows, macOS, and Linux evidence separately where supported; mark a platform outside the application's scope as not targeted. Shared Qt code does not imply identical fonts, layout metrics, alignment, or event behavior. | Target | What to distinguish and verify | | --- | --- | | Windows | The native `windows` platform plugin, available widget styles, font fallback, and display scaling are separate factors. Offscreen Qt can lack system fonts. A `Windows` style selected in an offscreen process checks that style's rendering, not native focus, activation, window frames, or desktop DPI behavior. | | macOS | Use a Mac and the native `cocoa` plugin for Cocoa-specific behavior. Preserve intentional native form-label alignment and centering. Check native control sizing, focus, accessibility, and Retina scaling when relevant. Fusion output or a mocked macOS branch elsewhere cannot establish Cocoa appearance or behavior. | | Linux | Record the actual display backend (`xcb`/X11 or Wayland), available style, fonts, and scale. A headless runner's font set can differ from a desktop's. Check the relevant backend for native focus, placement, decorations, or scaling defects; one Linux backend does not prove the other. | Discover available styles with `QStyleFactory.keys()` instead of assuming every host offers the same styles. Keep intentional platform defaults: `QFormLayout` alignment and field sizing may correctly differ. Test readable, nonoverlapping controls and intended alignment rather than identical pixel coordinates across operating systems. Use offscreen rendering for repeatable visual checks, then native verification on affected platforms when the changed contract depends on a platform plugin or desktop integration. If a target is unavailable, complete the available checks and name the remaining native verification. Never label a simulated platform branch, native style, or cross-platform source pass as a native OS test. ## Establish real font coverage - Inspect the application's font-loading code and any bundled font assets. Reuse their selection and sizes when they represent the target UI. If the project has no bundled fonts, use suitable installed fonts; bundling a new font is not a prerequisite for applying this skill. - Check font discovery in the actual preview process. For explicit registration, call `QFontDatabase.addApplicationFont` after QApplication creation and before widget construction, handle a failed result, and obtain the loaded family with `applicationFontFamilies`. Do not infer a family name from a font's filename. If fonts are unavailable, report the missing prerequisite or prepare an appropriate test-only dependency within the task's scope. - Verify the text under test with `QFontMetrics.inFontUcs4(ord(character))` in Python, or the corresponding Unicode code-point check in the project's binding. Use metrics from the actual widget font, including applicable styling. A loaded font may cover Latin but lack CJK, Arabic, or other required glyphs. Verify fallback coverage; a font file's existence alone proves neither selection nor successful rendering. Inspect shaping and fallback visually as well as checking individual glyphs. - An explicitly selected test font is a repeatable baseline, not proof of the production font's appearance. Use production font selection for native checks. Keep registration process-local. Do not alter desktop font preferences to make a preview pass; make necessary CI font dependencies explicit in its setup. - Do not introduce wrapping, enlarge dialogs, or override native alignment to compensate for missing-glyph measurements. First establish the defect with loaded fonts, then respect the requested layout and wrapping behavior. ## Render, inspect, and interact safely 1. Select the preview's Qt platform before application initialization; with Python, set it before Qt/application imports. Preserve the existing suite's backend. In a disposable preview, use offscreen rendering where supported and isolate settings, storage, and host/network effects. Apply the actual widget's production stylesheet or palette rather than approximating its appearance. 2. Show the disposable widget and wait for the required layout and content state. Reuse existing event helpers, or use a bounded Qt event loop with an observable readiness condition. Do not rely on arbitrary sleeps or introduce production `processEvents()` calls just to make a preview work. Capture with `QWidget.grab()` after the relevant state is displayed. Check capture success, save to a temporary or established scratch directory, and open the image with an available image viewer. Blank or incomplete captures are not evidence of correctness; use a supported rendering/capture path for the affected surface. 3. Inspect label and field edges, complete text, input content, alignment, spacing, contrast, and state indicators. Use full-widget context plus a crop when needed; do not infer appearance from rectangles alone. Exercise relevant keyboard, focus, and selection behavior with real Qt events, for example QTest. 4. For native checks, prefer an existing isolated fixture. If a visible preview is needed, use a separate diagnostic process with the target native plugin and only disposable windows. Disable or substitute startup integration such as singleton IPC, tray icons, session restoration, background services, and external operations where present. Do not interact with the user's running application or switch the normal suite's backend globally. Without visual access, report the limitation or obtain a targeted manual check; successful native process launch is not completed visual verification. 5. Close and destroy owned widgets and reap owned processes even on failure. Keep preview images out of source control unless requested or needed as an established regression fixture. Do not capture unrelated desktop content. ## Retain useful regressions and report evidence - Pair inspection with focused assertions for the discovered defect: glyph coverage, text fitting the available content area, no field overlap, intended wrapping, native alignment, tab order, or observable interaction state. Avoid exact preferred-width equality and whole-window snapshot equality unless those are the actual contract. - Run the relevant focused checks, then the affected suite or tier available in the project. Shared harness changes warrant broader verification. Native or packaged defects need evidence at that boundary; source tests cannot replace it. - State what you actually viewed and exercised, the Qt/binding version, platform plugin/style, font/fallback, relevant languages/themes/scales, test outcomes, and remaining platform gaps. Keep this proportional to the task. Distinguish automated assertions, inspected offscreen renders, native interaction, and packaged verification. Link a useful preview when it helps the user assess the result; never claim to have seen UI that was only generated or measured.