testudos.api.wait

testudos.api.wait

Waiting and lookup helpers.

wait_* helpers poll backend RPC actions until a condition is met or timeout. get_* helpers perform a single immediate lookup and return None if not found.

Dict targets with type resolve via spy descriptors (qmlName / logicalName / className) with findObjectByProperties as fallback. For UI exploration only, see :mod:testudos.api.debug.

get_object

def get_object(
    target: str | dict[str, Any],
    *,
    parent: str | dict[str, Any] | QtObjectProxy | None = None
) -> QtObjectProxy | None

Get an object immediately by name or properties.

When parent is set and target is a QML id string, search only inside that subtree (see :func:get_descendant).

Dict targets with type match spy qmlName / logicalName / className fields, then fall back to findObjectByProperties.

Returns None when no object exists at call time.

wait_for_object

def wait_for_object(
    target: str | dict[str, Any],
    timeout: float = 5,
    *,
    parent: str | dict[str, Any] | QtObjectProxy | None = None
) -> QtObjectProxy

Wait for an object to appear, then return a proxy.

• str: findObject (use parent to scope duplicate QML ids).
• dict with type: spy qmlName / logicalName / className, then findObjectByProperties fallback.
• dict without type: findObjectByProperties.

Arguments:

• target - Object name (str) or property filter (dict).
• timeout - Maximum wait in seconds (default 5).
• parent - Optional container limiting search to a subtree (str targets only).

Raises:

• TestudosTimeoutError - If the object is not found within timeout.

get_object_by_text

def get_object_by_text(text: str) -> QtObjectProxy | None

Get an object by text immediately.

Returns None when no object matches at call time.

wait_for_object_by_text

def wait_for_object_by_text(text: str, timeout: float = 5) -> QtObjectProxy

Wait for an object whose readable string property equals text.

get_object_item

def get_object_item(list_obj: str | QtObjectProxy,
                    item_text: str) -> QtObjectProxy | None

Get a direct child item under list_obj by exact text.

Returns None when no item matches at call time.

wait_for_object_item

def wait_for_object_item(list_obj: str | QtObjectProxy,
                         item_text: str,
                         timeout: float = 5) -> QtObjectProxy

Wait for a concrete direct-child item under list_obj whose text equals item_text.

Uses backend RPC action findObjectItem.

wait_for

def wait_for(condition: Callable[[], bool],
             timeout: float = 5,
             poll_interval: float = 0.1) -> None

Poll a boolean condition until it becomes True or timeout is reached.

wait_for_text

def wait_for_text(target: str | dict[str, Any] | QtObjectProxy,
                  expected_text: str,
                  timeout: float = 5,
                  poll_interval: float = 0.1) -> str

Wait until target.text equals expected_text and return the observed text.

wait_for_application_launch

def wait_for_application_launch(
        timeout: float = 10,
        poll_interval: float = 0.1,
        min_top_level_objects: int = 1) -> list[QtObjectProxy]

Wait until AUT exposes at least min_top_level_objects top-level objects.