Every feature.
One clear toolkit.

What it helps with. Turn a manual walkthrough into a test without writing it by hand.

Click, type, choose menus, scroll and drag in your Qt app. Double, right and modifier clicks, drop-down picks, shortcuts and window closes each become a readable line. Accents, dead keys and input methods are recorded as typed text. Hover-only actions and native macOS menus are not recorded.

What it helps with. Recorded steps still make sense when you open the file later.

The recorder writes the shortest unique selector, names list, tree and table items by their text instead of a screen position, and adds a wait before controls that just appeared or became enabled.

What it helps with. Extend a test without recording it again from the start.

Record replays the script to the end, then inserts the new steps above any closing quit or expect-exit steps. If the app quits while you record, an expect-exit step is added.

What it helps with. Start a test with its app, name and purpose already filled in.

File → New Recording (Ctrl+N) asks for the application, a file name and an optional description, then writes the script’s header lines. A shared prepare.py setup in the folder is picked up automatically.

What it helps with. Verify results, not just the actions that led to them.

While recording, press Check (Ctrl+Shift+K) and click a control. The click does not reach the app; TestHand adds a step that checks the control’s text, checked state, current item or value. Password fields are never captured.

What it helps with. Compare whole lists, tables, panels or drawings against a known-good result.

expect-approved compares a text snapshot, or a picture with --picture and an optional --max-diff tolerance. Approved results live in the script’s .approved folder. On a mismatch, TestHand saves the received result and a diff next to it.

What it helps with. Accept an intended change without editing files by hand.

Review the received result in the player’s Step tab and choose Approve or Reject, or run testhand approve SCRIPT from the command line. Approved pictures are not portable between platforms.

What it helps with. Stable tests without arbitrary pauses.

wait polls every 50 ms, without blocking the app, until a control exists, is visible, hidden, gone, enabled or disabled, a property has a value, or an image or text appears. A timeout explains what was still missing.

What it helps with. Check the effects that happen outside the window.

expect-files checks the files an action produced, with patterns, recursion and hidden files. expect-exit --code checks that the application exits with the expected status.

What it helps with. See the test run and keep the whole sequence in view.

Play continuously or step by step, set a speed from none to three seconds per step, and use Play/Pause, Step (F10) and Stop (Ctrl+.). Each step shows its state as the script runs.

What it helps with. Understand a failure at the moment it happened.

A failed step turns red and holds. Why it failed shows the error and a screenshot captured at failure. Play retries the step; double-click another step to continue from there.

What it helps with. Get to the step you are investigating quickly.

Toggle a breakpoint with F9 to hold before a step. Run to Selected Step (Ctrl+F10) and Run From Selected Step (Ctrl+Return) play only the part you need.

What it helps with. Run a whole folder of tests and read one summary.

Add scripts or folders by picking or dragging them in. A failed script does not stop the rest; each row shows Passed, Failed or Skipped. Save Summary writes a text report with the failure screenshots.

What it helps with. Fix a step where you found it.

Edit (Ctrl+E) opens the script in your editor at the selected step’s line. Saving the file reloads it in the player.

What it helps with. Reuse one test with different data and environments.

Scripts can use $NAME placeholders, filled in from the Variables tab or the environment. A #! setup: header runs a command whose NAME=VALUE output sets variables before the test starts.

What it helps with. Test the app you ship, not a special test build.

A generic Qt plugin is loaded into the application at launch, so no source changes or linking are needed. Qt Quick items can be found by QML type or file name, clicked, typed into and captured, including inside a QQuickWidget.

What it helps with. Name the exact control in a way that survives layout changes.

Target by class, #objectName, [property="value"] or a case-insensitive [property~=contains], with descendant and child steps and an index when several visible controls match. Menus and toolbars contain the actions they show.

What it helps with. Reach custom-painted controls that have no useful name.

Cut a reference picture with screenshot --region, then click, locate or wait for it. --text finds controls by the words they show, and read lists every line of text in a widget. Text recognition uses Apple Vision on macOS and tesseract elsewhere.

What it helps with. Focus, popups, modal dialogs and shortcuts behave as they do for a person.

Mouse and keyboard events enter Qt where real ones do. Clicks land where a person would click, scroll areas bring the target into view first, and clicking a disabled control is reported as an error.

What it helps with. Run a test without its windows covering your screen.

Turn Show the app off in the player, or use --platform offscreen, to run supported Qt tests with no visible window. Drag-and-drop started inside the app still plays back offscreen.

What it helps with. Drive signed, hardened or non-Qt applications from the outside.

Launch with --desktop or attach to a running process with --pid. Selectors use accessibility roles, input uses the real pointer and menu bar, and screen capture provides screenshots, text recognition and image search. QML items, recording, approved checks and offscreen runs are Qt-probe features.

What it helps with. Find a missing permission before the first failed step.

The desktop helper can check Accessibility and Screen Recording access with --check-access and open the right System Settings pane with --open-settings.

What it helps with. Your application and its data stay on your machine.

The probe listens on a local socket that only the current user can open, or a named pipe on Windows. There is no remote testing endpoint or hosted execution.

What it helps with. Know what is tested before you rely on it.

macOS and Linux are supported and tested. On Linux, the desktop backend needs X11, or XWayland under Wayland. Windows builds are cross-compiled and tested under Wine but not yet on real Windows. The probe needs Qt 6.5 or later, matching the app’s Qt version.

What it helps with. Script the same actions from a terminal.

python3 -m testhand provides launch, attach, tree, find, inspect, click, drag, scroll, select, type, key, menu, wait, screenshot, record, run and more. Every recorded script line is one of these commands.

What it helps with. Gate a build on a desktop test result.

python3 -m testhand.stepper SCRIPT --play runs a script without the player. It exits with 0 only when every step passed and the app exited cleanly, and --failure-shots DIR keeps the failure screenshots.

What it helps with. Compose tests in the language your tooling already uses.

The client/testhand library provides the probe connection, app launch and attach, approved-result checks, file checks and script reading, so setup and assertions can live in your own Python code.

What it helps with. Let an AI agent inspect and operate your app.

python3 -m testhand.mcp_server exposes 23 tools, including launch_app, get_tree, find, click, type_text, use_menu, wait_for and screenshot. Screenshots return as images, and the desktop backend is supported. Recording and approved checks are not MCP tools.