robotframework-appiumwindows 0.1.0__py3-none-any.whl

AppiumLibrary/keywords/_screenrecord.py

@@ -0,0 +1,138 @@
+# -*- coding: utf-8 -*-
+
+import base64
+import os
+
+import robot
+
+from .keywordgroup import KeywordGroup
+
+
+class _ScreenrecordKeywords(KeywordGroup):
+
+    def __init__(self):
+        self._screenrecord_index = 0
+        self._recording = None
+        self._output_format = None
+
+    def start_screen_recording(self,
+                               timeLimit='180s',
+                               **options):
+        """Starts an asynchronous Screen Recording for the current open application.
+
+        ``timeLimit`` sets the actual time limit of the recorded video.
+          - The default value for both iOS and Android is 180 seconds (3 minutes).
+          - The maximum value for Android is 3 minutes.
+          - The maximum value for iOS is 10 minutes.
+
+        === Optional Args ===
+
+         - ``bitRate`` (Android Only) The video bit rate for the video, in megabits per second.
+            4 Mbp/s(4000000) is by default for Android API level below 27.                      \
+              20 Mb/s(20000000) for API level 27 and above.
+
+         - ``videoSize`` (Android Only) The format is widthxheight. The default value is the    \
+            device's native display resolution (if supported), 1280x720 if not. For best        \
+                results, use a size supported by your device's Advanced Video Coding (AVC)      \
+                    encoder. For example, "1280x720"
+
+         - ``bugReport`` (Android Only) Set it to true in order to display additional           \
+            information on the video overlay, such as a timestamp, that is helpful in           \
+                videos captured to illustrate bugs. This option is only supported since         \
+                    API level 27 (Android O).
+
+         - ``videoQuality`` (iOS Only) The video encoding quality (low, medium, high,           \
+            photo - defaults to medium).
+
+         - ``videoFps`` 	(iOS Only) The Frames Per Second rate of the recorded video.        \
+            Change this value if the resulting video is too slow or too fast. Defaults to 10.   \
+                This can decrease the resulting file size.
+
+         - ``videoScale`` (iOS Only) The scaling value to apply. Read                           \
+            https://trac.ffmpeg.org/wiki/Scaling for possible values. Example value of 720p     \
+                scaling is '1280:720'. This can decrease/increase the resulting file size.      \
+                    No scale is applied by default.
+
+        `Start Screen Recording` is used hand in hand with `Stop Screen Recording`.
+        See `Stop Screen Recording` for more details.
+        Example:
+            | `Start Screen Recording`  |                   | # starts a screen record session  |
+            | ....     keyword actions  |                   |                                   |
+            | `Stop Screen Recording`   | filename=output   | # saves the recorded session      |
+        """
+        timeLimit = robot.utils.timestr_to_secs(timeLimit)
+        options['timeLimit'] = timeLimit
+        self._output_format = self._set_output_format() \
+            if self._output_format is None else self._output_format
+        if self._recording is None:
+            self._recording = self._current_application().start_recording_screen(**options)
+
+    def stop_screen_recording(self, filename=None, **options):
+        """Gathers the output from the previously started screen recording  \
+            to a media file, then embeds it to the log.html(Android Only).
+
+        Requires an active or exhausted Screen Recording Session.
+        See `Start Screen Recording` for more details.
+
+        === Optional Args ===
+
+         - ``remotePath`` The path to the remote location, where the resulting video should be  \
+            uploaded. The following protocols are supported _http/https_, ftp. Null or empty  \
+                string value (the default setting) means the content of resulting file should   \
+                    be encoded as Base64 and passed as the endpoint response value. An          \
+                        exception will be thrown if the generated media file is too big to fit  \
+                            into the available process memory.
+
+         - ``username`` The name of the user for the remote authentication.
+
+         - ``password`` The password for the remote authentication.
+
+         - ``method`` The http multipart upload method name. The _PUT_ one is used by default.
+
+        Example:
+            | `Start Screen Recording`  |                   | # starts a screen record session  |
+            | ....     keyword actions  |                   |                                   |
+            | `Stop Screen Recording`   | filename=output   | # saves the recorded session      |
+        """
+        if self._recording is not None:
+            self._recording = self._current_application().stop_recording_screen(**options)
+            return self._save_recording(filename, options)
+        else:
+            raise RuntimeError("There is no Active Screen Record Session.")
+
+    def _save_recording(self, filename, options):
+        path, link = self._get_screenrecord_paths(options, filename)
+        decoded = base64.b64decode(self._recording)
+        with open(path, 'wb') as screenrecording:
+            screenrecording.write(decoded)
+        # Embed the Screen Recording to the log file
+        # if the current platform is Android and no remotePath is set.
+        if self._is_android() and not self._is_remotepath_set(options):
+            self._html('</td></tr><tr><td colspan="3"><a href="{vid}">'
+                       '<video width="800px" controls>'
+                       '<source src="{vid}" type="video/mp4">'
+                       '</video></a>'.format(vid=link)
+                       )
+        # Empty Screen Record Variable
+        self._recording = None
+        return path
+
+    def _set_output_format(self):
+        return '.ffmpeg' if self._is_ios() else '.mp4'
+
+    def _get_screenrecord_paths(self, options, filename=None):
+        if filename is None:
+            self._screenrecord_index += 1
+            filename = 'appium-screenrecord-{index}{ext}'.format(index=self._screenrecord_index,
+                                                                 ext=self._output_format
+                                                                 )
+        else:
+            filename = (filename.replace('/', os.sep)) + self._output_format
+        logdir = options['remotePath'] if self._is_remotepath_set(options) \
+            else self._get_log_dir()
+        path = os.path.join(logdir, filename)
+        link = robot.utils.get_link_path(path, logdir)
+        return path, link
+
+    def _is_remotepath_set(self, options):
+        return True if 'remotePath' in options else False

AppiumLibrary/keywords/_screenshot.py

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+
+import os
+from base64 import b64decode
+
+import robot
+
+from .keywordgroup import KeywordGroup, ignore_on_fail
+
+
+class _ScreenshotKeywords(KeywordGroup):
+
+    # Public
+
+    def appium_get_element_screenshot(self, locator, timeout=20, filename=None):
+        """
+        Get a screenshot of element to base64
+        If provide filename, saves a screenshot to a PNG image file.
+
+        Parameters:
+        -----------
+        locator: Element locator
+        timeout: timeout in second to find element
+        filename : str
+            - The full path you wish to save your screenshot to. This
+            - should end with a `.png` extension.
+
+        Example:
+        --------
+        >>> driver.get_screenshot_as_file("/Screenshots/foo.png")
+        """
+
+        element = self._invoke_original("appium_get_element", locator, timeout, False)
+
+        if not element:
+            self._info(f'Not found {locator}, return None')
+            return None
+
+        base64data = element.screenshot_as_base64
+
+        if filename:
+            if not str(filename).lower().endswith(".png"):
+                self._info(
+                    "name used for saved screenshot does not match file type. It should end with a `.png` extension")
+
+            png = b64decode(base64data.encode("ascii"))
+            try:
+                with open(filename, "wb") as f:
+                    f.write(png)
+            except OSError:
+                self._info(f'Fail to write screenshot file {filename}, return False')
+                return False
+            finally:
+                del png
+            return True
+
+        return base64data
+
+    @ignore_on_fail
+    def appium_get_screenshot(self):
+        return self._invoke_original("appium_capture_page_screenshot", None, False)
+
+    def appium_capture_page_screenshot(self, filename=None, embed=True):
+        try:
+            return self._invoke_original("capture_page_screenshot", filename, embed)
+        except Exception as err:
+            self._info(err)
+        return None
+
+    def capture_page_screenshot(self, filename=None, embed=True):
+        """Takes a screenshot of the current page and embeds it into the log.
+
+        `filename` argument specifies the name of the file to write the
+        screenshot into. If no `filename` is given, the screenshot will be
+        embedded as Base64 image to the log.html. In this case no file is created in the filesystem.
+
+        `embed` is True: the screenshot will be embedded to the log.html
+
+        Warning: this behavior is new in 1.7. Previously if no filename was given
+        the screenshots where stored as separate files named `appium-screenshot-<counter>.png`
+        """
+        if filename:
+            path, link = self._get_screenshot_paths(filename)
+
+            if hasattr(self._current_application(), 'get_screenshot_as_file'):
+                self._current_application().get_screenshot_as_file(path)
+            else:
+                self._current_application().save_screenshot(path)
+
+            # Image is shown on its own row and thus prev row is closed on purpose
+            if embed:
+                self._html('</td></tr><tr><td colspan="3"><a href="%s">'
+                           '<img src="%s" width="800px"></a>' % (link, link))
+            return path
+        else:
+            base64_screenshot = self._current_application().get_screenshot_as_base64()
+            if embed:
+                self._html('</td></tr><tr><td colspan="3">'
+                           '<img src="data:image/png;base64, %s" width="800px">' % base64_screenshot)
+            return None
+
+    # Private
+
+    def _get_screenshot_paths(self, filename):
+        filename = filename.replace('/', os.sep)
+        logdir = self._get_log_dir()
+        path = os.path.join(logdir, filename)
+        link = robot.utils.get_link_path(path, logdir)
+        return path, link

AppiumLibrary/keywords/_waiting.py

@@ -0,0 +1,163 @@
+import time
+
+import robot
+
+from .keywordgroup import KeywordGroup
+
+
+class _WaitingKeywords(KeywordGroup):
+
+    def __init__(self):
+        self._sleep_between_wait = 0.2
+
+    def wait_until_element_is_visible(self, locator, timeout=None, error=None):
+        """Waits until element specified with `locator` is visible.
+
+        Fails if `timeout` expires before the element is visible. See
+        `introduction` for more information about `timeout` and its
+        default value.
+
+        `error` can be used to override the default error message.
+
+        See also `Wait Until Page Contains`, `Wait Until Page Contains 
+        Element`, `Wait For Condition` and BuiltIn keyword `Wait Until Keyword
+        Succeeds`.
+        """
+
+        def check_visibility():
+            visible = self._is_visible(locator)
+            if visible:
+                return
+            elif visible is None:
+                return error or "Element locator '%s' did not match any elements after %s" % (
+                locator, self._format_timeout(timeout))
+            else:
+                return error or "Element '%s' was not visible in %s" % (locator, self._format_timeout(timeout))
+
+        self._wait_until_no_error(timeout, check_visibility)
+
+    def wait_until_page_contains(self, text, timeout=None, error=None):
+        """Waits until `text` appears on current page.
+
+        Fails if `timeout` expires before the text appears. See
+        `introduction` for more information about `timeout` and its
+        default value.
+
+        `error` can be used to override the default error message.
+
+        See also `Wait Until Page Does Not Contain`,
+        `Wait Until Page Contains Element`,
+        `Wait Until Page Does Not Contain Element` and
+        BuiltIn keyword `Wait Until Keyword Succeeds`.
+        """
+        if not error:
+            error = "Text '%s' did not appear in <TIMEOUT>" % text
+        self._wait_until(timeout, error, self._is_text_present, text)
+
+    def wait_until_page_does_not_contain(self, text, timeout=None, error=None):
+        """Waits until `text` disappears from current page.
+
+        Fails if `timeout` expires before the `text` disappears. See
+        `introduction` for more information about `timeout` and its
+        default value.
+
+        `error` can be used to override the default error message.
+
+        See also `Wait Until Page Contains`,
+        `Wait Until Page Contains Element`,
+        `Wait Until Page Does Not Contain Element` and
+        BuiltIn keyword `Wait Until Keyword Succeeds`.
+        """
+
+        def check_present():
+            present = self._is_text_present(text)
+            if not present:
+                return
+            else:
+                return error or "Text '%s' did not disappear in %s" % (text, self._format_timeout(timeout))
+
+        self._wait_until_no_error(timeout, check_present)
+
+    def wait_until_page_contains_element(self, locator, timeout=None, error=None):
+        """Waits until element specified with `locator` appears on current page.
+
+        Fails if `timeout` expires before the element appears. See
+        `introduction` for more information about `timeout` and its
+        default value.
+
+        `error` can be used to override the default error message.
+
+        See also `Wait Until Page Contains`,
+        `Wait Until Page Does Not Contain`
+        `Wait Until Page Does Not Contain Element`
+        and BuiltIn keyword `Wait Until Keyword Succeeds`.
+        """
+        if not error:
+            error = "Element '%s' did not appear in <TIMEOUT>" % locator
+        self._wait_until(timeout, error, self._is_element_present, locator)
+
+    def wait_until_page_does_not_contain_element(self, locator, timeout=None, error=None):
+        """Waits until element specified with `locator` disappears from current page.
+
+        Fails if `timeout` expires before the element disappears. See
+        `introduction` for more information about `timeout` and its
+        default value.
+
+        `error` can be used to override the default error message.
+
+        See also `Wait Until Page Contains`,
+        `Wait Until Page Does Not Contain`,
+        `Wait Until Page Contains Element` and
+        BuiltIn keyword `Wait Until Keyword Succeeds`.
+        """
+
+        def check_present():
+            present = self._is_element_present(locator)
+            if not present:
+                return
+            else:
+                return error or "Element '%s' did not disappear in %s" % (locator, self._format_timeout(timeout))
+
+        self._wait_until_no_error(timeout, check_present)
+
+    def set_sleep_between_wait_loop(self, seconds=0.2):
+        """Sets the sleep in seconds used by wait until loop.
+        
+        If you use the remote appium server, the default value is not recommended because 
+        it is another 200ms overhead to the network latency and will slow down your test
+        execution.
+        """
+        old_sleep = self._sleep_between_wait
+        self._sleep_between_wait = robot.utils.timestr_to_secs(seconds)
+        return old_sleep
+
+    def get_sleep_between_wait_loop(self):
+        """Gets the sleep between wait loop in seconds that is used by wait until keywords.
+        """
+        return robot.utils.secs_to_timestr(self._sleep_between_wait)
+
+    # Private
+
+    def _wait_until(self, timeout, error, function, *args):
+        error = error.replace('<TIMEOUT>', self._format_timeout(timeout))
+
+        def wait_func():
+            return None if function(*args) else error
+
+        self._wait_until_no_error(timeout, wait_func)
+
+    def _wait_until_no_error(self, timeout, wait_func, *args):
+        timeout = robot.utils.timestr_to_secs(timeout) if timeout is not None else self._timeout_in_secs
+        maxtime = time.time() + timeout
+        while True:
+            timeout_error = wait_func(*args)
+            if not timeout_error:
+                return
+            if time.time() > maxtime:
+                self._invoke_original("log_source")
+                raise AssertionError(timeout_error)
+            time.sleep(self._sleep_between_wait)
+
+    def _format_timeout(self, timeout):
+        timeout = robot.utils.timestr_to_secs(timeout) if timeout is not None else self._timeout_in_secs
+        return robot.utils.secs_to_timestr(timeout)

AppiumLibrary/keywords/_windows.py

@@ -0,0 +1,215 @@
+import time
+
+from AppiumLibrary.keywords.keywordgroup import KeywordGroup
+
+
+class _WindowsKeywords(KeywordGroup):
+
+    def __init__(self):
+        super().__init__()
+
+    # Public
+    def appium_hover(self, locator, start_locator=None, timeout=20, **kwargs):
+        self._info(f"Appium Hover '{locator}', timeout '{timeout}'")
+        self._appium_hover_api(start_locator=start_locator, end_locator=locator, timeout=timeout, **kwargs)
+
+    def appium_click_offset(self, locator, x_offset=0, y_offset=0, timeout=20, **kwargs):
+        self._info(
+            f"Appium Click Offset '{locator}', (x_offset,y_offset) '({x_offset},{y_offset})', timeout '{timeout}'")
+        self._appium_click_api(locator=locator, timeout=timeout, x_offset=x_offset, y_offset=y_offset, **kwargs)
+
+    def appium_right_click(self, locator, timeout=20, **kwargs):
+        self._info(f"Appium Right Click '{locator}', timeout '{timeout}'")
+        self._appium_click_api(locator=locator, timeout=timeout, button="right", **kwargs)
+
+    def appium_left_click(self, locator, timeout=20, **kwargs):
+        self._info(f"Appium Left Click '{locator}', timeout '{timeout}'")
+        self._appium_click_api(locator=locator, timeout=timeout, button="left", **kwargs)
+
+    def appium_double_click(self, locator, timeout=20, **kwargs):
+        self._info(f"Appium Double Click '{locator}', timeout '{timeout}'")
+        self._appium_click_api(locator=locator, timeout=timeout, times=2, **kwargs)
+
+    def appium_drag_and_drop(self, start_locator=None, end_locator=None, timeout=20, **kwargs):
+        self._info(f"Appium Drag And Drop '{start_locator} -> {end_locator}', timeout '{timeout}'")
+        self._appium_drag_and_drop_api(start_locator=start_locator, end_locator=end_locator, timeout=timeout, **kwargs)
+
+    def appium_drag_and_drop_by_offset(self, x_start, y_start, x_end, y_end):
+        x_start, y_start, x_end, y_end = (int(x) for x in [x_start, y_start, x_end, y_end])
+        self._info(f"Appium Drag And Drop By Offset ({x_start}, {y_start}) -> ({x_end}, {y_end})")
+        self._appium_drag_and_drop_api(start_locator=None, end_locator=None, timeout=1,
+                                       startX=x_start, startY=y_start,
+                                       endX=x_end, endY=y_end)
+
+    def appium_sendkeys(self, text=None, **kwargs):
+        self._info(f"Appium Sendkeys '{text}'")
+        self._appium_keys_api(text=text, **kwargs)
+
+    # Private
+    def _apply_modifier_keys(self, params: dict, modifier_keys):
+        """Normalize modifier keys and update params in place."""
+        if modifier_keys:
+            if isinstance(modifier_keys, (list, tuple)):
+                params["modifierKeys"] = [str(k).lower() for k in modifier_keys]
+            else:
+                params["modifierKeys"] = str(modifier_keys).lower()
+
+    def _appium_click_api(self, locator, timeout, **kwargs):
+        """
+        Perform a click action on a Windows element using Appium Windows Driver.
+
+        References:
+            https://github.com/appium/appium-windows-driver
+            https://github.com/appium/appium-windows-driver?tab=readme-ov-file#windows-click
+
+        Args:
+            locator (str): Element locator.
+            timeout (int): Maximum time to retry locating and clicking the element (in seconds).
+            kwargs (dict): Additional click options.
+
+        Keyword Args:
+            button (str): Mouse button to click. One of:
+                - "left" (default)
+                - "middle"
+                - "right"
+                - "back"
+                - "forward"
+            modifierKeys (list|str): Keys to hold during the click. One or more of:
+                - "Shift"
+                - "Ctrl"
+                - "Alt"
+                - "Win"
+            modifier_keys (list|str): Same as `modifierKeys` (snake_case alias).
+            x_offset (int): X offset relative to the element's top-left corner. Default: 0.
+            y_offset (int): Y offset relative to the element's top-left corner. Default: 0.
+            is_center (bool): If True, click at the element's center. Default: False.
+            durationMs (int): Duration of the click in milliseconds. Default: 100.
+            times (int): Number of times to click. Default: 1.
+            interClickDelayMs (int): Delay between multiple clicks in milliseconds. Default: 100.
+            post_delay (float): Delay after click action (in seconds). Default: 0.5.
+
+        Raises:
+            Exception: If the element cannot be found or the click action fails within the timeout.
+        """
+        x_offset = int(kwargs.get("x_offset", 0))
+        y_offset = int(kwargs.get("y_offset", 0))
+        is_center = bool(kwargs.get("is_center", False))
+
+        click_params = {
+            "button": str(kwargs.get("button", "left")),
+            "durationMs": int(kwargs.get("durationMs", 100)),
+            "times": int(kwargs.get("times", 1)),
+            "interClickDelayMs": int(kwargs.get("interClickDelayMs", 100)),
+        }
+
+        self._apply_modifier_keys(click_params, kwargs.get("modifierKeys"))
+
+        def _action():
+            elements = self._element_find(locator, False, False)
+            if not elements:
+                raise Exception(f"Element not found: {locator}")
+
+            driver = self._current_application()
+            rect = driver.get_window_rect()
+            e_rect = elements[0].rect
+
+            x = rect['x'] + e_rect['x'] + x_offset
+            y = rect['y'] + e_rect['y'] + y_offset
+            if is_center:
+                x += e_rect['width'] // 2
+                y += e_rect['height'] // 2
+
+            click_params.update({"x": x, "y": y})
+            self._info(f"Click params {click_params}")
+
+            driver.execute_script("windows: click", click_params)
+            time.sleep(0.5)
+
+        self._retry(_action, timeout, f"Failed to perform click action on '{locator}'")
+
+    def _appium_hover_api(self, start_locator, end_locator, timeout, **kwargs):
+        """
+        Perform a hover action using Platform-Specific Extensions.
+        """
+        hover_params = {
+            "startX": int(kwargs.get("startX", 0)),
+            "startY": int(kwargs.get("startY", 0)),
+            "endX": int(kwargs.get("endX", 0)),
+            "endY": int(kwargs.get("endY", 0)),
+            "durationMs": int(kwargs.get("durationMs", 100)),
+        }
+
+        self._apply_modifier_keys(hover_params, kwargs.get("modifierKeys"))
+
+        def _action():
+            if start_locator:
+                start_element = self._element_find(start_locator, True, False)
+                if start_element:
+                    hover_params["startElementId"] = start_element.id
+                    hover_params.pop("startX", None)
+                    hover_params.pop("startY", None)
+
+            if end_locator:
+                end_element = self._element_find(end_locator, True, False)
+                if end_element:
+                    hover_params["endElementId"] = end_element.id
+                    hover_params.pop("endX", None)
+                    hover_params.pop("endY", None)
+
+            self._current_application().execute_script("windows: hover", hover_params)
+            time.sleep(0.5)
+
+        self._retry(_action, timeout, "Failed to perform hover action")
+
+    def _appium_drag_and_drop_api(self, start_locator, end_locator, timeout, **kwargs):
+        """
+        Perform a drag and drop action using Appium Windows Driver.
+        https://github.com/appium/appium-windows-driver?tab=readme-ov-file#windows-clickanddrag
+        """
+        drag_params = {
+            "startX": int(kwargs.get("startX", 0)),
+            "startY": int(kwargs.get("startY", 0)),
+            "endX": int(kwargs.get("endX", 0)),
+            "endY": int(kwargs.get("endY", 0)),
+            "durationMs": int(kwargs.get("durationMs", 5000)),
+        }
+
+        self._apply_modifier_keys(drag_params, kwargs.get("modifierKeys"))
+
+        def _action():
+            if start_locator:
+                start_element = self._element_find(start_locator, True, False)
+                if start_element:
+                    drag_params["startElementId"] = start_element.id
+                    drag_params.pop("startX", None)
+                    drag_params.pop("startY", None)
+
+            if end_locator:
+                end_element = self._element_find(end_locator, True, False)
+                if end_element:
+                    drag_params["endElementId"] = end_element.id
+                    drag_params.pop("endX", None)
+                    drag_params.pop("endY", None)
+
+            self._current_application().execute_script("windows: clickAndDrag", drag_params)
+            time.sleep(0.5)
+
+        self._retry(_action, timeout, "Failed to perform drag and drop action")
+
+    def _appium_keys_api(self, text, **kwargs):
+        """
+        Perform a key input action using Appium Windows Driver.
+        https://github.com/appium/appium-windows-driver?tab=readme-ov-file#windows-keys
+
+        @param text:
+        @param kwargs:
+        @return:
+        """
+        actions = kwargs.get("actions", "")
+        # pause = int(kwargs.get("pause", 0))
+        # virtual_key_code = int(kwargs.get("virtualKeyCode", 0))
+        # down = bool(kwargs.get("down", False))
+        if not actions:
+            actions = [{"text": text}]
+        self._current_application().execute_script("windows: keys", {"actions": actions})
+        time.sleep(0.5)