robotframework-desktop 0.1.0__py3-none-any.whl

DesktopLibrary/keywords/region.py

@@ -0,0 +1,288 @@
+import time
+
+from robot.api.deco import keyword
+
+from ..geometry import Match, Region, to_region
+from ..locator import parse_locator
+from .base import KeywordGroup
+
+
+class RegionKeywords(KeywordGroup):
+    # ---- ROI -----------------------------------------------------------------
+    @keyword
+    def set_roi(self, coordinates, timeout: float = 0):
+        """Sets the region of interest. Image searches without an explicit
+        ``region`` are limited to it. Optionally highlights it for ``timeout`` seconds.
+
+        Examples:
+        | ${coordinates}= | Create List | 0 | 0 | 800 | 600 |
+        | Set ROI | ${coordinates} |
+        | Set ROI | [100, 100, 400, 300] | 2 |
+        """
+        self.ctx.roi = to_region(coordinates)
+        if float(timeout) > 0:
+            self.ctx.overlay.highlight(self.ctx.roi, float(timeout))
+
+    @keyword
+    def reset_roi(self):
+        """Resets the region of interest to the whole current screen.
+
+        Example:
+        | Reset ROI |
+        """
+        self.ctx.roi = None
+
+    @keyword
+    def highlight_roi(self, timeout: float):
+        """Highlights the current region of interest for ``timeout`` seconds.
+
+        Example:
+        | Highlight ROI | 2 |
+        """
+        self.ctx.overlay.highlight(self.ctx.search_region(), float(timeout))
+
+    # ---- extended regions ------------------------------------------------------
+    @keyword
+    def get_extended_region_from(
+        self, element, direction: str, number_of_times_to_repeat
+    ):
+        """Returns a region above or below ``element`` with the same width and
+        height multiplied by ``number_of_times_to_repeat``.
+
+        Example:
+        | ${region}= | Get Extended Region From | label.png | below | 2 |
+        """
+        if str(direction).lower() not in ('above', 'below'):
+            raise ValueError("Direction must be 'above' or 'below'.")
+        return self.ctx.find(element).extended(
+            direction, number_of_times_to_repeat
+        )
+
+    @keyword
+    def get_extended_region_from_image(
+        self, element, direction: str, number_of_times_to_repeat=1
+    ):
+        """Returns a region next to ``element`` (``above``, ``below``, ``left``,
+        ``right`` or ``original``) scaled by ``number_of_times_to_repeat``.
+
+        With ``original`` the region is the element itself.
+
+        Examples:
+        | ${region}= | Get Extended Region From Image | image.png | below | 1 |
+        | ${region}= | Get Extended Region From Image | name:Total | right | 3 |
+        | ${region}= | Get Extended Region From Image | image.png | original | 1 |
+        """
+        return self.ctx.find(element).extended(
+            direction, number_of_times_to_repeat
+        )
+
+    @keyword
+    def get_extended_region_from_region(
+        self, region, direction: str, number_of_times_to_repeat=1
+    ):
+        """Same as `Get Extended Region From Image` but starting from ``region``.
+
+        Example:
+        | ${below}= | Get Extended Region From Region | ${another_region} | below | 1 |
+        """
+        return to_region(region).extended(direction, number_of_times_to_repeat)
+
+    @keyword
+    def from_region_jump_to(
+        self, region, direction: str, jumps: int, margin: int = 1
+    ):
+        """Returns a copy of ``region`` translated ``jumps`` times its own size
+        plus ``margin`` pixels in ``direction`` (``above``, ``below``, ``left``, ``right``).
+
+        Example:
+        | ${next_row}= | From Region Jump To | ${row} | below | 4 | 1 |
+        """
+        return to_region(region).jump(direction, jumps, margin)
+
+    @keyword
+    def return_match_from_region(self, region, target):
+        """Searches ``target`` inside ``region`` and returns the match, usable
+        with `Click On Match`.
+
+        Example:
+        | ${region}= | Get Extended Region From | header.png | below | 3 |
+        | ${match}= | Return Match From Region | ${region} | item.png |
+        | Click On Match | ${match} |
+        """
+        locator = parse_locator(target).with_region(to_region(region))
+        return self.ctx.find(locator)
+
+    @keyword
+    def get_region(self, element) -> Region:
+        """Returns the region (``x``, ``y``, ``width``, ``height``) of ``element``.
+
+        Example:
+        | ${r}= | Get Region | name:OK |
+        | Log | ${r.x} ${r.y} ${r.width} ${r.height} |
+        """
+        return Region(*self.ctx.find(element).to_tuple())
+
+    # ---- screens ---------------------------------------------------------------
+    @keyword
+    def change_screen_id(self, screen_id: int):
+        """Selects the monitor used as default search area. ``0`` is the
+        primary monitor; ``-1`` means all monitors (whole virtual desktop).
+
+        Examples:
+        | Change Screen Id | 1 |
+        | Change Screen Id | -1 |
+        """
+        screen_id = int(screen_id)
+        count = len(self.ctx.monitors())
+        if not -1 <= screen_id < count:
+            raise ValueError(
+                f'Screen id {screen_id} out of range (0..{count - 1}).'
+            )
+        self.ctx.screen_id = screen_id
+
+    @keyword
+    def get_current_screen_id(self) -> int:
+        """Returns the current screen id.
+
+        Example:
+        | ${id}= | Get Current Screen Id |
+        """
+        return self.ctx.screen_id
+
+    @keyword
+    def get_number_of_screens(self) -> int:
+        """Returns the number of connected monitors.
+
+        Example:
+        | ${n}= | Get Number Of Screens |
+        """
+        return len(self.ctx.monitors())
+
+    @keyword
+    def get_screen_coordinates(self) -> list:
+        """Returns ``[x, y, width, height]`` of the current screen.
+
+        Example:
+        | @{coordinates}= | Get Screen Coordinates |
+        """
+        return self.ctx.screen().to_list()
+
+    # ---- capture ---------------------------------------------------------------
+    def _capture(
+        self, region: Region, name: str = '', prefix='capture'
+    ) -> str:
+        path = self.ctx.next_capture_path(name, prefix)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.ctx.image.grab(region).save(path)
+        from robot.api import logger
+
+        logger.info(
+            f'<img src="{path.as_posix()}" width="{min(region.width, 800)}">',
+            html=True,
+        )
+        return str(path)
+
+    @keyword
+    def capture_screen(self, image_name: str = '') -> str:
+        """Captures the current screen and returns the file path.
+
+        Examples:
+        | ${file}= | Capture Screen |
+        | ${file}= | Capture Screen | home.png |
+        """
+        return self._capture(self.ctx.screen(), image_name, 'screen')
+
+    @keyword
+    def capture_region(self, coordinates, image_name: str = '') -> str:
+        """Captures region ``coordinates`` ``[x, y, w, h]`` and returns the file path.
+
+        Relative names are saved in the capture folder (see `Set Capture Folder`).
+
+        Examples:
+        | ${coor}= | Create List | 0 | 0 | 300 | 200 |
+        | ${file}= | Capture Region | ${coor} | demo.png |
+        | ${file}= | Capture Region | ${coor} |
+        """
+        return self._capture(to_region(coordinates), image_name, 'region')
+
+    @keyword
+    def capture_roi(self, image_name: str = '') -> str:
+        """Captures the region of interest and returns the file path.
+
+        Example:
+        | ${file}= | Capture ROI | roi.png |
+        """
+        return self._capture(self.ctx.search_region(), image_name, 'roi')
+
+    @keyword
+    def capture_element(self, element, image_name: str = '') -> str:
+        """Captures the area of ``element`` and returns the file path. Useful
+        to create reference images from UI Automation elements.
+
+        Example:
+        | ${file}= | Capture Element | automation_id:btnSave | images/save.png |
+        """
+        match = self.ctx.find(element)
+        return self._capture(Region(*match.to_tuple()), image_name, 'element')
+
+    @keyword
+    def select_region(self, message: str = 'Select a region') -> list:
+        """Lets the user drag a rectangle on screen, captures it and returns
+        ``[captured_image_path, x, y, w, h]``. Fails if cancelled with ESC.
+
+        Example:
+        | @{selected}= | Select Region | Select the area to capture |
+        """
+        region = self.ctx.overlay.select_region(message, self.ctx.screen())
+        if region is None:
+            raise AssertionError('Region selection was cancelled.')
+        time.sleep(0.2)
+        return [self._capture(region, '', 'selected'), *region.to_list()]
+
+    # ---- highlight -------------------------------------------------------------
+    @keyword
+    def highlight(self, element, secs=''):
+        """Highlights ``element``. If ``secs`` is given the highlight vanishes
+        automatically, otherwise it stays until `Clear Highlight`.
+
+        Examples:
+        | Highlight | button.png | 2 |
+        | Highlight | name:OK |
+        | Clear Highlight | name:OK |
+        """
+        match = self.ctx.find(element)
+        seconds = float(secs) if str(secs).strip() else 0
+        self.ctx.overlay.highlight(match, seconds, key=_key(element))
+
+    @keyword
+    def highlight_region(self, coordinates, timeout: float):
+        """Highlights region ``coordinates`` for ``timeout`` seconds.
+
+        Example:
+        | Highlight Region | [0, 0, 200, 100] | 2 |
+        """
+        self.ctx.overlay.highlight(to_region(coordinates), float(timeout))
+
+    @keyword
+    def clear_highlight(self, element):
+        """Removes the highlight created by `Highlight` for ``element``.
+
+        Example:
+        | Clear Highlight | button.png |
+        """
+        self.ctx.overlay.clear(_key(element))
+
+    @keyword
+    def clear_all_highlights(self):
+        """Removes all highlights from the screen.
+
+        Example:
+        | Clear All Highlights |
+        """
+        self.ctx.overlay.clear_all()
+
+
+def _key(element) -> str:
+    if isinstance(element, (Match, Region)):
+        return str(Region(*element.to_tuple()))
+    return repr(element) if not isinstance(element, str) else element

DesktopLibrary/keywords/wait.py

@@ -0,0 +1,178 @@
+import time
+
+from robot.api.deco import keyword
+
+from ..locator import parse_locator
+from .base import KeywordGroup
+
+
+class WaitKeywords(KeywordGroup):
+    @keyword
+    def exists(self, element, timeout='') -> bool:
+        """Returns ``True`` if ``element`` appears within ``timeout``, ``False`` otherwise.
+
+        ``timeout`` defaults to the library timeout (see `Set Timeout`).
+
+        Examples:
+        | ${found}= | Exists | popup.png | 0 |
+        | ${found}= | Exists | name:Confirm | 3s |
+        | IF | ${found} | Click | ok.png |
+        """
+        return self.ctx.exists(element, timeout)
+
+    @keyword
+    def screen_should_contain(self, element, timeout=''):
+        """Fails unless ``element`` is visible (waiting up to ``timeout``).
+
+        Examples:
+        | Screen Should Contain | logo.png |
+        | Screen Should Contain | automation_id:mainWindow | 10s |
+        """
+        secs = self.ctx.to_seconds(timeout, self.ctx.timeout)
+        self.ctx.cursor.auto_wait(secs)
+        self.ctx.find(element, secs, wait_cursor=False)
+
+    @keyword
+    def screen_should_not_contain(self, element):
+        """Fails if ``element`` is currently visible (no waiting).
+
+        Example:
+        | Screen Should Not Contain | error.png |
+        """
+        locator = parse_locator(element)
+        if self.ctx.find_now(locator):
+            raise AssertionError(
+                f"Screen should not contain '{locator.describe()}'."
+            )
+
+    @keyword
+    def wait_until_screen_contain(self, element, timeout=''):
+        """Waits until ``element`` appears on screen and returns the match.
+
+        Examples:
+        | Wait Until Screen Contain | loaded.png | 30 |
+        | ${m}= | Wait Until Screen Contain | name:Ready | 10s |
+        """
+        secs = self.ctx.to_seconds(timeout, self.ctx.timeout)
+        self.ctx.cursor.auto_wait(secs)
+        return self.ctx.find(element, secs, wait_cursor=False)
+
+    @keyword
+    def wait_until_screen_not_contain(self, element, timeout=''):
+        """Waits until ``element`` disappears from the screen.
+
+        Example:
+        | Wait Until Screen Not Contain | spinner.png | 60 |
+        """
+        if not self.ctx.wait_vanish(element, timeout):
+            raise AssertionError(
+                f"Element '{parse_locator(element).describe()}' still visible after timeout."
+            )
+
+    @keyword
+    def wait_for_image(self, wanted_element, not_wanted_element, timeout):
+        """Waits for ``wanted_element``; fails if ``not_wanted_element`` appears
+        first or the ``timeout`` expires.
+
+        Example:
+        | Wait For Image | success.png | error.png | 10 |
+        """
+        return self.wait_for_multiple_images(
+            timeout, 0, [wanted_element], [not_wanted_element]
+        )
+
+    @keyword
+    def wait_for_multiple_images(
+        self, timeout, polling_interval, expected_images, not_expected_images
+    ):
+        """Waits until any of ``expected_images`` appears and returns it.
+
+        Fails if any of ``not_expected_images`` appears first or ``timeout``
+        expires. ``polling_interval`` is the time in seconds between checks
+        (``0`` uses the wait scan rate).
+
+        Example:
+        | @{wanted}= | Create List | done1.png | done2.png |
+        | @{unwanted}= | Create List | error1.png | name:Error |
+        | ${found}= | Wait For Multiple Images | 900 | 10 | ${wanted} | ${unwanted} |
+        """
+        timeout = self.ctx.to_seconds(timeout)
+        interval = float(polling_interval) or (1.0 / self.ctx.scan_rate)
+        wanted = [(e, parse_locator(e)) for e in _as_list(expected_images)]
+        unwanted = [
+            (e, parse_locator(e)) for e in _as_list(not_expected_images)
+        ]
+        deadline = time.monotonic() + timeout
+        while True:
+            for raw, loc in unwanted:
+                if self.ctx.find_now(loc):
+                    raise AssertionError(
+                        f"Not expected element '{loc.describe()}' appeared."
+                    )
+            for raw, loc in wanted:
+                matches = self.ctx.find_now(loc)
+                if matches:
+                    self.ctx.last_match = matches[0]
+                    return raw
+            if time.monotonic() >= deadline:
+                names = ', '.join(loc.describe() for _, loc in wanted)
+                raise AssertionError(
+                    f'None of the expected elements appeared: {names}.'
+                )
+            time.sleep(interval)
+
+    @keyword
+    def image_count(self, element) -> int:
+        """Returns how many times ``element`` is currently found on screen.
+
+        Example:
+        | ${count}= | Image Count | checkbox.png |
+        | Should Be Equal As Integers | ${count} | 3 |
+        """
+        return len(self.ctx.find_all(element))
+
+    @keyword
+    def get_match_score(self, element) -> float:
+        """Returns the best match score (0-1) of ``element`` on screen.
+
+        For image locators the score is computed even when below the minimum
+        similarity. For UI locators returns ``1.0`` if found, otherwise ``0.0``.
+
+        Example:
+        | ${score}= | Get Match Score | maybe.png |
+        | IF | ${score} > 0.95 | Click | maybe.png |
+        """
+        locator = parse_locator(element)
+        if locator.kind == 'image':
+            return self.ctx.image.best_score(
+                locator, self.ctx.search_region(locator)
+            )
+        return 1.0 if self.ctx.find_now(locator) else 0.0
+
+    @keyword
+    def get_image_coordinates(self, element, coordinates=None) -> list:
+        """Returns ``[x, y, width, height]`` of ``element``.
+
+        If ``coordinates`` ``[x, y, w, h]`` is given, searches only there.
+
+        Examples:
+        | ${coords}= | Get Image Coordinates | image.png=0.75 |
+        | ${coords}= | Get Image Coordinates | image.png | [0, 0, 800, 600] |
+        | ${coords}= | Get Image Coordinates | automation_id:btnSave |
+        """
+        from ..geometry import to_region
+
+        region = (
+            to_region(coordinates)
+            if coordinates not in (None, '', [])
+            else None
+        )
+        return self.ctx.find(element, region=region).to_list()
+
+
+def _as_list(value):
+    if value in (None, ''):
+        return []
+    if isinstance(value, (list, tuple)):
+        return list(value)
+    return [value]

DesktopLibrary/locator.py

@@ -0,0 +1,223 @@
+import re
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from .geometry import Match, Region, to_offset, to_region
+
+IMAGE_EXTENSIONS = ('.png', '.jpg', '.jpeg', '.bmp')
+
+# User facing key -> pywinauto find_elements criteria name
+UI_KEY_ALIASES = {
+    'name': 'title',
+    'title': 'title',
+    'name_re': 'title_re',
+    'title_re': 'title_re',
+    'automation_id': 'auto_id',
+    'automationid': 'auto_id',
+    'auto_id': 'auto_id',
+    'id': 'auto_id',
+    'class': 'class_name',
+    'class_name': 'class_name',
+    'classname': 'class_name',
+    'class_name_re': 'class_name_re',
+    'control_type': 'control_type',
+    'type': 'control_type',
+    'handle': 'handle',
+    'process': 'process',
+    'found_index': 'found_index',
+    'index': 'found_index',
+}
+UI_PREFIXES = ('uia', 'win32')
+_INT_KEYS = {'handle', 'process', 'found_index'}
+
+
+@dataclass
+class Locator:
+    """Normalized element locator.
+
+    ``kind`` is ``image``, ``ui`` or ``region``.
+    """
+
+    kind: str
+    images: list[str] = field(default_factory=list)
+    similarity: float | None = None
+    offset: tuple[int, int] = (0, 0)
+    region: Region | None = None
+    criteria: dict[str, Any] = field(default_factory=dict)
+    backend: str | None = None
+    fixed: Region | None = None
+    raw: Any = None
+
+    def with_region(self, region: Region | None) -> 'Locator':
+        return replace(self, region=region)
+
+    def with_extra_offset(self, x: int = 0, y: int = 0) -> 'Locator':
+        return replace(
+            self, offset=(self.offset[0] + int(x), self.offset[1] + int(y))
+        )
+
+    def describe(self) -> str:
+        if self.kind == 'image':
+            text = ' | '.join(self.images)
+        elif self.kind == 'ui':
+            text = ' AND '.join(f'{k}:{v}' for k, v in self.criteria.items())
+            if self.backend:
+                text = f'{self.backend}:{text}'
+        else:
+            text = str(self.fixed)
+        return text
+
+
+def _ui_criteria_from_string(text: str) -> dict[str, Any] | None:
+    parts = re.split(r'\s+AND\s+', text.strip())
+    criteria: dict[str, Any] = {}
+    for part in parts:
+        m = re.match(r'^\s*([A-Za-z_]+)\s*[:=]\s*(.*?)\s*$', part, re.S)
+        if not m or m.group(1).lower() not in UI_KEY_ALIASES:
+            return None
+        key = UI_KEY_ALIASES[m.group(1).lower()]
+        criteria[key] = _coerce_ui_value(key, m.group(2))
+    return criteria
+
+
+def _coerce_ui_value(key: str, value: Any) -> Any:
+    if (
+        key in _INT_KEYS
+        and isinstance(value, str)
+        and value.strip().lstrip('-').isdigit()
+    ):
+        return int(value)
+    return value
+
+
+def _split_similarity(path: str) -> tuple[str, float | None]:
+    """Support Sikuli style ``image.png=0.85``."""
+    m = re.match(
+        r'^(.*\.(?:png|jpe?g|bmp))\s*=\s*([0-9]*\.?[0-9]+)$', path, re.I
+    )
+    if m:
+        return m.group(1), float(m.group(2))
+    return path, None
+
+
+def _normalize_similarity(value: Any) -> float | None:
+    if value is None or value == '':
+        return None
+    value = float(value)
+    if value > 1:  # allow percent values such as 85
+        value = value / 100.0
+    if not 0 < value <= 1:
+        raise ValueError(f'Similarity must be between 0 and 1, got {value}.')
+    return value
+
+
+def parse_locator(value: Any) -> Locator:
+    """Convert a keyword ``element`` argument into a :class:`Locator`."""
+    if isinstance(value, Locator):
+        return value
+    if isinstance(value, Match):
+        return Locator(
+            kind='region', fixed=value, offset=tuple(value.offset), raw=value
+        )
+    if isinstance(value, Region):
+        return Locator(kind='region', fixed=value, raw=value)
+    if isinstance(value, dict):
+        return _parse_dict(value)
+    if isinstance(value, (list, tuple)):
+        if len(value) == 4 and all(isinstance(v, (int, float)) for v in value):
+            return Locator(kind='region', fixed=to_region(value), raw=value)
+        return _parse_dict({'path': list(value)})
+    if value is None or str(value).strip() == '':
+        raise ValueError('Element locator cannot be empty.')
+    return _parse_string(str(value))
+
+
+def _parse_string(text: str) -> Locator:
+    stripped = text.strip()
+    lower = stripped.lower()
+    if lower.startswith('image:'):
+        path, sim = _split_similarity(stripped[6:].strip())
+        return Locator(kind='image', images=[path], similarity=sim, raw=text)
+    for prefix in UI_PREFIXES:
+        if lower.startswith(prefix + ':'):
+            criteria = _ui_criteria_from_string(stripped[len(prefix) + 1 :])
+            if not criteria:
+                raise ValueError(f"Invalid UI locator '{text}'.")
+            return Locator(
+                kind='ui', criteria=criteria, backend=prefix, raw=text
+            )
+    criteria = _ui_criteria_from_string(stripped)
+    if criteria:
+        return Locator(kind='ui', criteria=criteria, raw=text)
+    path, sim = _split_similarity(stripped)
+    return Locator(kind='image', images=[path], similarity=sim, raw=text)
+
+
+def _parse_dict(data: dict) -> Locator:
+    lower = {str(k).lower(): v for k, v in data.items()}
+    offset = to_offset(lower.get('offset'))
+    region = (
+        to_region(lower['region'])
+        if lower.get('region') not in (None, '')
+        else None
+    )
+    similarity = _normalize_similarity(lower.get('similarity'))
+    backend = lower.get('backend')
+    if backend is not None:
+        backend = str(backend).lower()
+        if backend not in UI_PREFIXES:
+            raise ValueError(
+                f"Invalid backend '{backend}'. Use 'uia' or 'win32'."
+            )
+
+    if 'path' in lower:
+        paths = lower['path']
+        if isinstance(paths, str):
+            paths = [paths]
+        paths = [str(p) for p in paths]
+        if not paths:
+            raise ValueError("Locator 'path' cannot be empty.")
+        return Locator(
+            kind='image',
+            images=paths,
+            similarity=similarity,
+            offset=offset,
+            region=region,
+            raw=data,
+        )
+
+    if 'locator' in lower:
+        base = parse_locator(lower['locator'])
+        return replace(
+            base,
+            offset=(base.offset[0] + offset[0], base.offset[1] + offset[1]),
+            region=region or base.region,
+            similarity=similarity
+            if similarity is not None
+            else base.similarity,
+            backend=backend or base.backend,
+            raw=data,
+        )
+
+    criteria = {}
+    for key, val in lower.items():
+        if key in UI_KEY_ALIASES:
+            mapped = UI_KEY_ALIASES[key]
+            criteria[mapped] = _coerce_ui_value(mapped, val)
+    if criteria:
+        return Locator(
+            kind='ui',
+            criteria=criteria,
+            backend=backend,
+            offset=offset,
+            region=region,
+            raw=data,
+        )
+
+    if region is not None:
+        return Locator(kind='region', fixed=region, offset=offset, raw=data)
+
+    raise ValueError(
+        f"Invalid element locator {data!r}. Use 'path' for images or UI keys such as "
+        f"'name', 'automation_id', 'class_name', 'control_type'."
+    )