Quick start - Python

A full working test in 15 lines.

Prerequisites

• Your Qt application is running with veriCue embedded (see Installation) on TCP port 4242.
• pip install vericue done.

Your first test

import asyncio
from vericue import VeriCueClient

async def main():
    async with VeriCueClient() as client:
        await client.connect("127.0.0.1", 4242)

        # Discover the OK button
        obj = await client.find_object(path="MainWindow/centralWidget/okButton")
        print("Found:", obj["className"])  # → QPushButton

        # Click it
        await client.mouse_click("MainWindow/centralWidget/okButton")

        # Assert the result
        props = await client.get_properties("MainWindow/statusLabel", ["text"])
        assert props["text"] == "Logged in"

asyncio.run(main())

Common operations

Discover objects

# By path
btn = await client.find_object(path="MainWindow/okButton")

# By class - returns a list
buttons = await client.list_objects(class_name="QPushButton")

# Browse the full tree from a root
tree = await client.get_object_tree(root="MainWindow", depth=3)

Interact

await client.mouse_click("MainWindow/okButton")
await client.type_text("MainWindow/searchBox", "hello world")
await client.key_press("MainWindow/searchBox", "Return")
await client.scroll("MainWindow/list", dy=-100)
await client.drag("MainWindow/canvas", 10, 10, 200, 150)  # drag within a widget

Read and write properties

# Read multiple properties at once
props = await client.get_properties(
    "MainWindow/usernameField", ["text", "enabled", "visible"]
)

# Write a property (triggers NOTIFY signal)
await client.set_property("MainWindow/themeSelector", "currentIndex", 2)

Wait for state changes

# Wait up to 5 s for a property to reach a value
await client.wait_for_property(
    "MainWindow/statusLabel", "text", "Ready",
    timeout=5000,
)

# Wait for a one-shot signal
await client.wait_for_signal(
    "MainWindow/loadButton", "clicked", timeout=10000,
)

Screenshots and visual regression

# Save a screenshot of a widget
data = await client.screenshot(path="MainWindow/canvas")
with open("canvas.png", "wb") as f:
    f.write(base64.b64decode(data["data"]))

# Compare against a baseline image file
result = await client.compare_screenshot_file(
    "canvas_baseline.png",
    path="MainWindow/canvas",
    threshold=0.02,  # allow 2% pixel difference
)
assert result["match"], f"Similarity: {result['similarity']}"

Subscribe to push events

For tests that drive UI flows and need to wait for any of N possible outcomes, use push subscriptions:

sub_id = await client.subscribe_signal(
    "MainWindow/okButton", "clicked",
    callback=lambda event: print("Clicked at", event["timestamp"]),
)

# ... trigger flow ...

await client.unsubscribe(sub_id)

See the Push events reference for full details.

Use it from pytest

veriCue ships a pytest plugin (auto-registered when vericue is installed). It provides three fixtures:

async def test_login(vericue_client):
    # Already connected, with handshake complete. Disconnects on teardown.
    await vericue_client.type_text("MainWindow/userField", "alice")
    await vericue_client.type_text("MainWindow/passField", "secret")
    await vericue_client.mouse_click("MainWindow/loginBtn")

    await vericue_client.wait_for_property(
        "MainWindow/statusLabel", "text", "Logged in",
        timeout=5000,
    )

For multi-connection scenarios use the vericue_client_factory fixture to make multiple clients in the same test.

For multi-process Qt applications use MultiVeriCueClient - see Multi-process testing.