robotframework-desktop 0.1.0__py3-none-any.whl

DesktopLibrary/keywords/cursor.py

@@ -0,0 +1,201 @@
+from robot.api.deco import keyword
+
+from ..cursor import normalize_cursor_types
+from .base import KeywordGroup
+
+
+class CursorKeywords(KeywordGroup):
+    @keyword
+    def get_current_cursor_type(self) -> str:
+        """Returns the current mouse cursor type.
+
+        Possible values: ``arrow``, ``ibeam``, ``wait``, ``cross``, ``uparrow``,
+        ``sizenwse``, ``sizenesw``, ``sizewe``, ``sizens``, ``sizeall``, ``no``,
+        ``hand``, ``appstarting``, ``help``, ``custom`` (application specific
+        cursor) or ``none`` (hidden cursor).
+
+        Examples:
+        | ${cursor}= | Get Current Cursor Type |
+        | Should Be Equal | ${cursor} | arrow |
+        """
+        return self.ctx.cursor.current()
+
+    @keyword
+    def cursor_should_be(self, expected):
+        """Fails unless the current cursor is one of ``expected``.
+
+        ``expected`` can be a name, numeric id (e.g. ``32514``), a comma
+        separated string or a list.
+
+        Examples:
+        | Cursor Should Be | arrow |
+        | Cursor Should Be | arrow,ibeam |
+        | Cursor Should Be | 32512 |
+        """
+        types = normalize_cursor_types(expected)
+        current = self.ctx.cursor.current()
+        if current not in types:
+            raise AssertionError(
+                f"Cursor is '{current}', expected one of: {', '.join(types)}."
+            )
+
+    @keyword
+    def cursor_should_not_be(self, unexpected):
+        """Fails if the current cursor is one of ``unexpected``.
+
+        Examples:
+        | Cursor Should Not Be | wait |
+        | Cursor Should Not Be | wait,appstarting |
+        """
+        types = normalize_cursor_types(unexpected)
+        current = self.ctx.cursor.current()
+        if current in types:
+            raise AssertionError(f"Cursor should not be '{current}'.")
+
+    @keyword
+    def wait_for_cursor_type(self, expected, timeout='30s') -> str:
+        """Waits until the cursor becomes one of ``expected`` and returns it.
+
+        Examples:
+        | Wait For Cursor Type | hand |
+        | Wait For Cursor Type | 32649 |
+        | Wait For Cursor Type | hand,arrow | 10s |
+        | ${cursor}= | Wait For Cursor Type | ${cursor_list} | timeout=1 min |
+        """
+        types = normalize_cursor_types(expected)
+        secs = self.ctx.to_seconds(timeout)
+        ok, cursor, _ = self.ctx.cursor.wait_until(
+            lambda c: c in types, secs, 0, 'type'
+        )
+        if not ok:
+            raise AssertionError(
+                f"Cursor did not become {', '.join(types)} in {secs:g} seconds "
+                f"(current: '{cursor}')."
+            )
+        return cursor
+
+    @keyword
+    def wait_until_cursor_is_not_busy(
+        self, timeout='', stable_duration='', fail_on_timeout=None
+    ) -> str:
+        """Waits until the cursor is not busy for ``stable_duration`` and
+        returns the final cursor type.
+
+        Busy types are defined by `Set Busy Cursor Types` (default ``wait`` and
+        ``appstarting``). Empty arguments use the values configured on import
+        or with `Set Busy Cursor Wait`. Unlike the automatic wait, this keyword
+        always waits the stability window, even when the cursor is not busy at start.
+
+        Examples:
+        | Click | load_button.png |
+        | Wait Until Cursor Is Not Busy |
+        | Wait Until Cursor Is Not Busy | 2 min | 1s |
+        | Wait Until Cursor Is Not Busy | 10s | fail_on_timeout=False |
+        """
+        mon = self.ctx.cursor
+        secs = self.ctx.to_seconds(timeout, mon.timeout)
+        stable = self.ctx.to_seconds(stable_duration, mon.stable_duration)
+        fail = (
+            mon.fail_on_timeout
+            if fail_on_timeout in (None, '')
+            else _bool(fail_on_timeout)
+        )
+        return mon.wait_not_busy(secs, stable, fail)
+
+    @keyword
+    def wait_for_normalized_cursor(
+        self, stable_duration='2s', timeout='30s', cursor=None
+    ) -> str:
+        """Waits until the cursor stops changing for ``stable_duration``.
+
+        If ``cursor`` is given, the stable cursor must be of that type.
+        Useful when an action makes the cursor oscillate between types.
+
+        Examples:
+        | Wait For Normalized Cursor |
+        | Wait For Normalized Cursor | stable_duration=1.5 |
+        | Wait For Normalized Cursor | cursor=arrow | timeout=60 |
+        | ${final}= | Wait For Normalized Cursor | 1s |
+        """
+        secs = self.ctx.to_seconds(timeout)
+        stable = self.ctx.to_seconds(stable_duration)
+        types = (
+            normalize_cursor_types(cursor)
+            if cursor not in (None, '')
+            else None
+        )
+        ok, final, changes = self.ctx.cursor.wait_until(
+            lambda c: types is None or c in types, secs, stable, 'normalized'
+        )
+        if not ok:
+            wanted = f" as {', '.join(types)}" if types else ''
+            raise AssertionError(
+                f"Cursor did not stabilize{wanted} in {secs:g} seconds (current: '{final}', "
+                f'changes: {len(changes)}).'
+            )
+        return final
+
+    @keyword
+    def set_busy_cursor_wait(
+        self,
+        enabled=True,
+        timeout='',
+        stable_duration='',
+        fail_on_timeout=None,
+        after_delay='',
+    ) -> dict:
+        """Configures the automatic busy cursor wait and returns the previous
+        configuration as a dictionary.
+
+        When enabled, keywords that act on the application wait while the
+        cursor is busy before searching elements, before mouse/keyboard
+        actions and after the action (watching ``after_delay`` seconds for the
+        cursor to become busy). When the cursor stays busy longer than
+        ``timeout`` the keyword fails (``fail_on_timeout=True``) or logs a
+        warning and continues.
+
+        Examples:
+        | Set Busy Cursor Wait | False |
+        | Set Busy Cursor Wait | True | timeout=2 min | stable_duration=1s |
+        | Set Busy Cursor Wait | True | fail_on_timeout=False |
+        | Set Busy Cursor Wait | True | after_delay=0.5s |
+        | ${old}= | Set Busy Cursor Wait | False |
+        | Set Busy Cursor Wait | &{old} |
+        """
+        mon = self.ctx.cursor
+        previous = {
+            'enabled': mon.enabled,
+            'timeout': mon.timeout,
+            'stable_duration': mon.stable_duration,
+            'fail_on_timeout': mon.fail_on_timeout,
+            'after_delay': mon.after_delay,
+        }
+        mon.enabled = _bool(enabled)
+        if str(after_delay).strip():
+            mon.after_delay = self.ctx.to_seconds(after_delay)
+        if str(timeout).strip():
+            mon.timeout = self.ctx.to_seconds(timeout)
+        if str(stable_duration).strip():
+            mon.stable_duration = self.ctx.to_seconds(stable_duration)
+        if fail_on_timeout not in (None, ''):
+            mon.fail_on_timeout = _bool(fail_on_timeout)
+        return previous
+
+    @keyword
+    def set_busy_cursor_types(self, types) -> list:
+        """Sets which cursor types are considered busy and returns the
+        previous list. Default: ``wait,appstarting``.
+
+        Examples:
+        | Set Busy Cursor Types | wait,appstarting,custom |
+        | Set Busy Cursor Types | wait |
+        """
+        previous = list(self.ctx.cursor.busy_types)
+        self.ctx.cursor.busy_types = normalize_cursor_types(types)
+        return previous
+
+
+def _bool(value) -> bool:
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in ('true', '1', 'yes', 'on')

DesktopLibrary/keywords/element.py

@@ -0,0 +1,260 @@
+from robot.api.deco import keyword
+
+from ..geometry import Match
+from ..locator import parse_locator
+from .base import KeywordGroup, busy_action
+
+
+class ElementKeywords(KeywordGroup):
+    """Keywords that need a real UI Automation element (UI locators only)."""
+
+    def _element(self, element):
+        if isinstance(element, Match) and element.element is not None:
+            self.ctx.cursor.auto_wait()
+            self.ctx.last_match = element
+            return element.element
+        locator = parse_locator(element)
+        if locator.kind != 'ui':
+            raise ValueError(
+                f"'{locator.describe()}' is not a UI locator. Use e.g. 'automation_id:txtName'."
+            )
+        match = self.ctx.find(locator)
+        return match.element
+
+    @keyword
+    def get_element_text(self, element) -> str:
+        """Returns the text/value of a UI element.
+
+        Examples:
+        | ${text}= | Get Element Text | automation_id:lblStatus |
+        | Should Be Equal | ${text} | Saved |
+        """
+        el = self._element(element)
+        for getter in ('get_value', 'window_text'):
+            try:
+                value = getattr(el, getter)()
+                if value not in (None, ''):
+                    return str(value)
+            except Exception:
+                continue
+        try:
+            return '\n'.join(t for t in el.texts() if t)
+        except Exception:
+            return ''
+
+    @keyword
+    @busy_action
+    def set_element_value(self, element, value: str):
+        """Sets the value of an edit control directly (no typing simulation).
+
+        Example:
+        | Set Element Value | automation_id:txtName | John |
+        """
+        el = self._element(element)
+        if hasattr(el, 'set_edit_text'):
+            el.set_edit_text(str(value))
+        elif hasattr(el, 'set_value'):
+            el.set_value(str(value))
+        else:
+            el.set_focus()
+            el.type_keys(str(value), with_spaces=True, set_foreground=True)
+
+    @keyword
+    def get_element_property(self, element, name: str):
+        """Returns an element property. Supported names include ``name``,
+        ``automation_id``, ``class_name``, ``control_type``, ``enabled``,
+        ``visible``, ``rectangle``, ``handle``, ``process_id`` and any
+        pywinauto ``element_info`` attribute.
+
+        Examples:
+        | ${enabled}= | Get Element Property | automation_id:btnSave | enabled |
+        | ${type}= | Get Element Property | name:OK | control_type |
+        """
+        el = self._element(element)
+        info = el.element_info
+        key = str(name).lower()
+        special = {
+            'name': lambda: info.name,
+            'automation_id': lambda: info.automation_id,
+            'class_name': lambda: info.class_name,
+            'control_type': lambda: info.control_type,
+            'enabled': el.is_enabled,
+            'visible': el.is_visible,
+            'rectangle': lambda: self.ctx.ui.region_of(el),
+            'handle': lambda: info.handle,
+            'process_id': lambda: info.process_id,
+            'text': el.window_text,
+        }
+        if key in special:
+            return special[key]()
+        if hasattr(info, name):
+            return getattr(info, name)
+        if hasattr(el, name):
+            attr = getattr(el, name)
+            return attr() if callable(attr) else attr
+        raise ValueError(f"Unknown property '{name}'.")
+
+    @keyword
+    @busy_action
+    def select_combobox_item(self, element, item: str):
+        """Selects ``item`` (text or 0 based index) in a combo box or list.
+
+        Examples:
+        | Select Combobox Item | automation_id:cmbColor | Blue |
+        | Select Combobox Item | automation_id:cmbColor | 2 |
+        """
+        el = self._element(element)
+        target = int(item) if str(item).isdigit() else str(item)
+        try:
+            el.select(target)
+            return
+        except Exception:
+            pass
+        # Fallback: open the drop down with the mouse and click the item.
+        el.click_input()
+        criteria = (
+            {'control_type': 'ListItem'} if el.backend.name == 'uia' else {}
+        )
+        if isinstance(target, str):
+            criteria['title'] = target
+        else:
+            criteria['found_index'] = target
+        items = self.ctx._poll(
+            lambda: self.ctx.ui.find_elements(
+                criteria, el.backend.name, parent=el
+            )
+            or self.ctx.ui.find_elements(
+                criteria, el.backend.name, use_window=False
+            ),
+            self.ctx.timeout,
+        )
+        if not items:
+            raise AssertionError(f"Item '{item}' not found.")
+        items[0].click_input()
+
+    @keyword
+    @busy_action
+    def set_checkbox_state(self, element, checked: bool = True):
+        """Checks or unchecks a checkbox.
+
+        Examples:
+        | Set Checkbox State | name:Remember me | ${TRUE} |
+        | Set Checkbox State | automation_id:chkAgree | ${FALSE} |
+        """
+        el = self._element(element)
+        wanted = str(checked).lower() in ('true', '1', 'yes', 'on')
+        state = (
+            el.get_toggle_state()
+            if hasattr(el, 'get_toggle_state')
+            else el.get_check_state()
+        )
+        if bool(state) != wanted:
+            if hasattr(el, 'toggle'):
+                el.toggle()
+            else:
+                el.click()
+
+    @keyword
+    @busy_action
+    def expand_tree_item(self, element, path: str = ''):
+        """Expands a tree item. If ``path`` (e.g. ``Root\\Child``) is given,
+        ``element`` is the tree and the item at ``path`` is expanded.
+
+        Examples:
+        | Expand Tree Item | name:Documents |
+        | Expand Tree Item | automation_id:treeFolders | Root\\\\Child |
+        """
+        el = self._element(element)
+        if path:
+            el = el.get_item(path)
+        el.expand()
+
+    @keyword
+    @busy_action
+    def invoke_element(self, element):
+        """Invokes (activates) an element through UI Automation without
+        moving the mouse.
+
+        Example:
+        | Invoke Element | automation_id:btnSave |
+        """
+        el = self._element(element)
+        if hasattr(el, 'invoke'):
+            el.invoke()
+        else:
+            el.click()
+
+    @keyword
+    def element_should_be_enabled(self, element):
+        """Fails if the UI element is disabled.
+
+        Example:
+        | Element Should Be Enabled | automation_id:btnSave |
+        """
+        if not self._element(element).is_enabled():
+            raise AssertionError(
+                f"Element '{parse_locator(element).describe()}' is disabled."
+            )
+
+    @keyword
+    def element_should_be_disabled(self, element):
+        """Fails if the UI element is enabled.
+
+        Example:
+        | Element Should Be Disabled | automation_id:btnSave |
+        """
+        if self._element(element).is_enabled():
+            raise AssertionError(
+                f"Element '{parse_locator(element).describe()}' is enabled."
+            )
+
+    @keyword
+    def element_should_be_visible(self, element):
+        """Fails if the UI element is not visible.
+
+        Example:
+        | Element Should Be Visible | name:Status |
+        """
+        if not self._element(element).is_visible():
+            raise AssertionError(
+                f"Element '{parse_locator(element).describe()}' is not visible."
+            )
+
+    @keyword
+    def get_window_tree(self, window='', depth: int = 4) -> str:
+        """Returns (and logs) the control tree of ``window`` or the attached
+        window. Helpful to discover locators.
+
+        Examples:
+        | Attach To Window | name:Sample App |
+        | ${tree}= | Get Window Tree |
+        | ${tree}= | Get Window Tree | name:Untitled - Notepad | 6 |
+        """
+        from robot.api import logger
+
+        el = (
+            self._element(window)
+            if window not in (None, '')
+            else self.ctx.ui.window
+        )
+        if el is None:
+            raise AssertionError(
+                "No window given or attached. Use 'Attach To Window'."
+            )
+        lines: list[str] = []
+
+        def walk(node, level):
+            info = node.element_info
+            lines.append(
+                f"{'   ' * level}{info.control_type or info.class_name} "
+                f"name='{info.name}' automation_id='{getattr(info, 'automation_id', '')}' "
+                f"class_name='{info.class_name}' rect={self.ctx.ui.region_of(node).to_list()}"
+            )
+            if level < int(depth):
+                for child in node.children():
+                    walk(child, level + 1)
+
+        walk(el, 0)
+        text = '\n'.join(lines)
+        logger.info(text)
+        return text

DesktopLibrary/keywords/find.py

@@ -0,0 +1,136 @@
+from robot.api import logger
+from robot.api.deco import keyword
+
+from ..geometry import Match, sort_matches
+from ..locator import parse_locator
+from .base import KeywordGroup
+
+
+class FindKeywords(KeywordGroup):
+    """Keywords returning elements so they can be iterated in loops."""
+
+    @keyword
+    def find_element(self, element, timeout='') -> Match:
+        """Returns the best match of ``element``, waiting up to ``timeout``
+        (default: library timeout). Fails if not found.
+
+        The returned match can be passed to any keyword accepting an element
+        (`Click`, `Input Text`, `Get Element Text`, `Highlight`...). For UI
+        locators it keeps the UI Automation element, so element keywords do
+        not search again. Attributes: ``x``, ``y``, ``width``, ``height``,
+        ``center``, ``target``, ``score``, ``source``.
+
+        Examples:
+        | ${save}= | Find Element | automation_id:btnSave |
+        | Click | ${save} |
+        | ${logo}= | Find Element | logo.png | 10s |
+        | Log | ${logo.x} ${logo.y} ${logo.score} |
+        """
+        return self.ctx.find(element, timeout)
+
+    @keyword
+    def find_elements(
+        self, element, timeout=0, sort_by: str = 'row', min_count: int = 0
+    ) -> list:
+        """Returns all matches of ``element`` as a list, or an empty list
+        when nothing is found.
+
+        - ``timeout``: wait up to this time for at least one match (default ``0``: no wait).
+        - ``sort_by``: ``row`` (top to bottom, then left to right, default),
+          ``column`` (left to right, then top to bottom), ``score`` (best first) or ``none``.
+        - ``min_count``: fail if fewer matches are found.
+
+        Each item is a match usable with any element keyword. Image matches
+        are screen positions: if the screen scrolls or changes while looping,
+        their coordinates become stale. UI matches keep the UI Automation element.
+
+        Examples:
+        | @{items}= | Find Elements | control_type:ListItem |
+        | FOR | ${item} | IN | @{items} |
+        | | ${text}= | Get Element Text | ${item} |
+        | | IF | $text == "Item 3" | Click | ${item} |
+        | END |
+        | @{boxes}= | Find Elements | checkbox.png | sort_by=column | min_count=2 |
+        | @{none}= | Find Elements | name:Not There |
+        | Should Be Empty | ${none} |
+        """
+        secs = self.ctx.to_seconds(timeout, 0)
+        matches = sort_matches(
+            self.ctx.find_all(element, secs, wait_cursor=True), sort_by
+        )
+        _check_min(matches, min_count, element)
+        logger.info(
+            f"Found {len(matches)} element(s) for '{parse_locator(element).describe()}'."
+        )
+        return matches
+
+    @keyword
+    def get_element_count(self, element) -> int:
+        """Returns how many times ``element`` is currently found (image or UI).
+
+        Examples:
+        | ${count}= | Get Element Count | control_type:Button |
+        | ${icons}= | Get Element Count | icon.png |
+        """
+        return len(self.ctx.find_all(element))
+
+    @keyword
+    def find_child_elements(
+        self,
+        element,
+        child='',
+        depth=None,
+        sort_by: str = 'none',
+        min_count: int = 0,
+    ) -> list:
+        """Returns the descendants of UI ``element`` matching the UI locator
+        ``child`` (all descendants when empty), or an empty list.
+
+        ``depth=1`` returns direct children only; empty means any depth.
+        ``element`` can be a UI locator or a match returned by `Find Element`.
+
+        Examples:
+        | @{items}= | Find Child Elements | automation_id:lstItems | control_type:ListItem |
+        | @{direct}= | Find Child Elements | ${WINDOW} | depth=1 |
+        | @{buttons}= | Find Child Elements | ${WINDOW} | control_type:Button | sort_by=column |
+        | FOR | ${b} | IN | @{buttons} |
+        | | Log | ${b.source} |
+        | END |
+        """
+        parent = self._ui_element(element)
+        criteria = {}
+        backend = None
+        if child not in (None, ''):
+            loc = parse_locator(child)
+            if loc.kind != 'ui':
+                raise ValueError(f"'{child}' is not a UI locator.")
+            criteria, backend = loc.criteria, loc.backend
+        depth = None if depth in (None, '') else int(depth)
+        wrappers = self.ctx.ui.find_children(parent, criteria, depth, backend)
+        source = (
+            parse_locator(child).describe()
+            if child not in (None, '')
+            else 'child'
+        )
+        matches = sort_matches(
+            self.ctx.ui.to_matches(wrappers, source), sort_by
+        )
+        _check_min(matches, min_count, child or element)
+        return matches
+
+    def _ui_element(self, element):
+        if isinstance(element, Match) and element.element is not None:
+            return element.element
+        locator = parse_locator(element)
+        if locator.kind != 'ui':
+            raise ValueError(f"'{locator.describe()}' is not a UI locator.")
+        return self.ctx.find(locator).element
+
+
+def _check_min(matches, min_count, element):
+    min_count = int(min_count or 0)
+    if len(matches) < min_count:
+        raise AssertionError(
+            f'Expected at least {min_count} element(s) for '
+            f"'{parse_locator(element).describe()}', found {len(matches)}."
+        )