Appium-Python-Client 5.2.0__py3-none-any.whl

appium/webdriver/extensions/flutter_integration/flutter_commands.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from appium.common.helper import encode_file_to_base64
+from appium.webdriver.extensions.flutter_integration.flutter_finder import FlutterFinder
+from appium.webdriver.extensions.flutter_integration.scroll_directions import ScrollDirection
+from appium.webdriver.webdriver import WebDriver
+from appium.webdriver.webelement import WebElement
+
+
+class FlutterCommand:
+    def __init__(self, driver: WebDriver) -> None:
+        self.driver = driver
+
+    # wait commands
+
+    def wait_for_visible(
+        self,
+        locator: Union[WebElement, FlutterFinder],
+        timeout: Optional[float] = None,
+    ) -> None:
+        """
+        Waits for a element to become visible.
+
+        Args:
+            locator (Union[WebElement, FlutterFinder]): The element to wait for; can be a WebElement or a FlutterFinder.
+            timeout (Optional[float]): Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
+
+        Returns:
+            None
+        """
+        opts: Dict[str, Any] = self.__get_locator_options(locator)
+        if timeout is not None:
+            opts['timeout'] = timeout
+
+        self.execute_flutter_command('waitForVisible', opts)
+
+    def wait_for_invisible(
+        self,
+        locator: Union[WebElement, FlutterFinder],
+        timeout: Optional[float] = None,
+    ) -> None:
+        """
+        Waits for a element to become invisible.
+
+        Args:
+            locator (Union[WebElement, FlutterFinder]): The element to wait for; can be a WebElement or a FlutterFinder.
+            timeout (Optional[float]): Maximum wait time in seconds. Defaults to a predefined timeout if not specified.
+
+        Returns:
+            None:
+        """
+        opts: Dict[str, Any] = self.__get_locator_options(locator)
+        if timeout is not None:
+            opts['timeout'] = timeout
+
+        self.execute_flutter_command('waitForAbsent', opts)
+
+    # flutter action commands
+
+    def perform_double_click(self, element: WebElement, offset: Optional[Tuple[int, int]] = None) -> None:
+        """
+        Performs a double-click on the given element, with an optional offset.
+
+        Args:
+            element (WebElement): The element to double-click on. This parameter is required.
+            offset (Optional[Tuple[int, int]]): The x and y offsets from the element to click at. If not specified, the click is performed at the element's center.
+
+        Returns:
+            None:
+        """
+        opts: Dict[str, Union[WebElement, Dict[str, int]]] = {'origin': element}
+        if offset is not None:
+            opts['offset'] = {'x': offset[0], 'y': offset[1]}
+        self.execute_flutter_command('doubleClick', opts)
+
+    def perform_long_press(self, element: WebElement, offset: Optional[Tuple[int, int]] = None) -> None:
+        """
+        Performs a long press on the given element, with an optional offset.
+
+        Args:
+            element (WebElement): The element to perform the long press on. This parameter is required.
+            offset (Optional[Tuple[int, int]]): The x and y offsets from the element to perform the long press at. If not specified, the long press is performed at the element's center.
+
+        Returns:
+            None:
+        """
+        opts: Dict[str, Union[WebElement, Dict[str, int]]] = {'origin': element}
+        if offset is not None:
+            opts['offset'] = {'x': offset[0], 'y': offset[1]}
+        self.execute_flutter_command('longPress', opts)
+
+    def perform_drag_and_drop(self, source: WebElement, target: WebElement) -> None:
+        """
+        Performs a drag-and-drop operation from a source element to a target element.
+
+        Args:
+            source (WebElement): The element to drag from.
+            target (WebElement): The element to drop onto.
+
+        Returns:
+            None:
+        """
+        self.execute_flutter_command('dragAndDrop', {'source': source, 'target': target})
+
+    def scroll_till_visible(
+        self,
+        scroll_to: FlutterFinder,
+        scroll_direction: ScrollDirection = ScrollDirection.DOWN,
+        **opts: Any,
+    ) -> WebElement:
+        """
+        Scrolls until the specified element becomes visible.
+
+        Args:
+            scroll_to (FlutterFinder): The Flutter element to scroll to.
+            scroll_direction (ScrollDirection): The direction to scroll up or down. Defaults to `ScrollDirection.DOWN`.
+
+        KeywordArgs:
+                scrollView (str): The view of the scroll. Default value is 'Scrollable'
+                delta (int): delta for the scroll. Default value is 64
+                maxScrolls (int): Max times to scroll. Default value is 15
+                settleBetweenScrollsTimeout (float): settle timeout in milliseconds. Default value is 5000
+                dragDuration (float): time gap between each scroll in milliseconds. Default value is 100
+
+        Returns:
+            Webelement: scrolled element
+        """
+        opts['finder'] = scroll_to.to_dict()
+        opts['scrollDirection'] = scroll_direction.value
+        return self.execute_flutter_command('scrollTillVisible', opts)
+
+    def inject_mock_image(self, value: str) -> str:
+        """
+        Injects a mock image to the device. The input can be a file path or a base64-encoded string.
+
+        Args:
+            value (str): The file path of the image or a base64-encoded string.
+
+        Returns:
+            str: Image ID of the injected image.
+        """
+        if os.path.isfile(value):
+            base64_encoded_image = encode_file_to_base64(value)
+        else:
+            base64_encoded_image = value
+        return self.execute_flutter_command('injectImage', {'base64Image': base64_encoded_image})
+
+    def activate_injected_image(self, image_id: str) -> None:
+        """
+        Activates an injected image with image ID.
+
+        Args:
+            image_id (str): The ID of the injected image to activate.
+
+        Returns:
+            None:
+        """
+        self.execute_flutter_command('activateInjectedImage', {'imageId': image_id})
+
+    def get_render_tree(
+        self,
+        widget_type: Optional[str] = None,
+        key: Optional[str] = None,
+        text: Optional[str] = None,
+    ) -> List[Optional[Dict]]:
+        """
+        Returns the render tree of the root widget.
+
+        Args:
+            widget_type (Optional[str]): The type of the widget to primary filter by.
+            key (Optional[str]): The key of the widget to filter by.
+            text (Optional[str]): The text of the widget to filter by.
+
+        Returns:
+            List[Optional[Dict]]: A list of dictionaries or None values representing the render tree.
+
+            The result is a nested list of dictionaries representing each widget and its properties,
+            such as type, key, size, attribute, state, visual information, and hierarchy.
+
+            The example widget includes the following code, which is rendered as part of the widget tree:
+
+            .. code-block:: dart
+
+                Semantics(
+                    key: const Key('add_activity_semantics'),
+                    label: 'add_activity_button',
+                    button: true,
+                    child: FloatingActionButton.small(
+                        key: const Key('add_activity_button'),
+                        tooltip: 'add_activity_button',
+                        heroTag: 'add',
+                        backgroundColor: const Color(0xFF2E2E3A),
+                        onPressed: null,
+                        child: Icon(
+                        Icons.add,
+                        size: 16,
+                        color: Colors.amber.shade200.withOpacity(0.5),
+                        semanticLabel: 'Add icon',
+                        ),
+                    ),
+                )
+
+        Example execute command:
+
+            .. code-block:: python
+
+                >>> flutter_command = FlutterCommand(driver)  # noqa
+                >>> flutter_command.get_render_tree(widget_type='Semantics', key='add_activity_semantics')
+                output >> [
+                            {
+                                "type": "Semantics",
+                                "elementType": "SingleChildRenderObjectElement",
+                                "description": "Semantics-[<'add_activity_semantics'>]",
+                                "depth": 0,
+                                "key": "[<'add_activity_semantics'>]",
+                                "attributes": {
+                                    "semanticsLabel": "add_activity_button"
+                                },
+                                "visual": {},
+                                "state": {},
+                                "rect": {
+                                    "x": 0,
+                                    "y": 0,
+                                    "width": 48,
+                                    "height": 48
+                                },
+                                "children": [
+                                    {
+                                        "type": "FloatingActionButton",
+                                        "elementType": "StatelessElement",
+                                        "description": "FloatingActionButton-[<'add_activity_button'>]",
+                                        "depth": 1,
+                                        "key": "[<'add_activity_button'>]",
+                                        "attributes": {},
+                                        "visual": {},
+                                        "state": {},
+                                        "rect": {
+                                            "x": 0,
+                                            "y": 0,
+                                            "width": 48,
+                                            "height": 48
+                                        },
+                                        "children": [
+                                            {...},
+                                                "children": [...]
+                                            }
+                                        ]
+                                    }
+                                ]
+                            }
+                        ]
+        """
+        opts = {}
+        if widget_type is not None:
+            opts['widgetType'] = widget_type
+        if key is not None:
+            opts['key'] = key
+        if text is not None:
+            opts['text'] = text
+
+        return self.execute_flutter_command('renderTree', opts)
+
+    def execute_flutter_command(self, scriptName: str, params: dict) -> Any:
+        """
+        Executes a Flutter command by sending a script and parameters to the flutter integration driver.
+
+        Args:
+            scriptName (str): The name of the Flutter command to execute.
+                This will be prefixed with 'flutter:' when passed to the driver.
+            params (dict): A dictionary of parameters to be passed along with the Flutter command.
+
+        Returns:
+            Any: The result of the command execution. The return value depends on the
+            specific Flutter command being executed.
+        """
+        return self.driver.execute_script(f'flutter: {scriptName}', params)
+
+    def __get_locator_options(self, locator: Union[WebElement, 'FlutterFinder']) -> Dict[str, Union[dict, WebElement]]:
+        if isinstance(locator, WebElement):
+            return {'element': locator}
+        return {'locator': locator.to_dict()}

appium/webdriver/extensions/flutter_integration/flutter_finder.py

@@ -0,0 +1,55 @@
+# Licensed to the Software Freedom Conservancy (SFC) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The SFC licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+from typing import Tuple, Union, cast
+
+from selenium.webdriver.common.by import ByType as SeleniumByType
+
+from appium.webdriver.common.appiumby import AppiumBy
+from appium.webdriver.common.appiumby import ByType as AppiumByType
+
+
+class FlutterFinder:
+    def __init__(self, using: Union[SeleniumByType, AppiumByType], value: str) -> None:
+        self.using = using
+        self.value = value
+
+    @staticmethod
+    def by_key(value: str) -> 'FlutterFinder':
+        return FlutterFinder(cast(AppiumByType, AppiumBy.FLUTTER_INTEGRATION_KEY), value)
+
+    @staticmethod
+    def by_text(value: str) -> 'FlutterFinder':
+        return FlutterFinder(cast(AppiumByType, AppiumBy.FLUTTER_INTEGRATION_TEXT), value)
+
+    @staticmethod
+    def by_semantics_label(value: str) -> 'FlutterFinder':
+        return FlutterFinder(cast(AppiumByType, AppiumBy.FLUTTER_INTEGRATION_SEMANTICS_LABEL), value)
+
+    @staticmethod
+    def by_type(value: str) -> 'FlutterFinder':
+        return FlutterFinder(cast(AppiumByType, AppiumBy.FLUTTER_INTEGRATION_TYPE), value)
+
+    @staticmethod
+    def by_text_containing(value: str) -> 'FlutterFinder':
+        return FlutterFinder(cast(AppiumByType, AppiumBy.FLUTTER_INTEGRATION_TEXT_CONTAINING), value)
+
+    def to_dict(self) -> dict:
+        return {'using': self.using, 'value': self.value}
+
+    def as_args(self) -> Tuple[str, str]:
+        return self.using, self.value

appium/webdriver/extensions/flutter_integration/scroll_directions.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class ScrollDirection(Enum):
+    UP = 'up'
+    DOWN = 'down'

appium/webdriver/extensions/hw_actions.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Optional
+
+from selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
+
+from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
+from appium.protocols.webdriver.can_execute_scripts import CanExecuteScripts
+from appium.protocols.webdriver.can_remember_extension_presence import CanRememberExtensionPresence
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class HardwareActions(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def lock(self, seconds: Optional[int] = None) -> Self:
+        """Lock the device. No changes are made if the device is already unlocked.
+
+        Args:
+            seconds: The duration to lock the device, in seconds.
+                The device is going to be locked forever until `unlock` is called
+                if it equals or is less than zero, otherwise this call blocks until
+                the timeout expires and unlocks the screen automatically.
+
+        Returns:
+            Union['WebDriver', 'HardwareActions']: Self instance
+        """
+        ext_name = 'mobile: lock'
+        args = {'seconds': seconds or 0}
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name, args)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.LOCK, args)
+        return self
+
+    def unlock(self) -> Self:
+        """Unlock the device. No changes are made if the device is already locked.
+
+        Returns:
+            Union['WebDriver', 'HardwareActions']: Self instance
+        """
+        ext_name = 'mobile: unlock'
+        try:
+            if not self.assert_extension_exists(ext_name).execute_script('mobile: isLocked'):
+                return self
+            self.execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.UNLOCK)
+        return self
+
+    def is_locked(self) -> bool:
+        """Checks whether the device is locked.
+
+        Returns:
+            `True` if the device is locked
+        """
+        ext_name = 'mobile: isLocked'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script('mobile: isLocked')
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.IS_LOCKED)['value']
+
+    def shake(self) -> Self:
+        """Shake the device.
+
+        Returns:
+            Union['WebDriver', 'HardwareActions']: Self instance
+        """
+        ext_name = 'mobile: shake'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.SHAKE)
+        return self
+
+    def touch_id(self, match: bool) -> Self:
+        """Simulate touchId on iOS Simulator
+
+        Args:
+            match: Simulates a successful touch (`True`) or a failed touch (`False`)
+
+        Returns:
+            Union['WebDriver', 'HardwareActions']: Self instance
+        """
+        self.execute_script(
+            'mobile: sendBiometricMatch',
+            {
+                'type': 'touchId',
+                'match': match,
+            },
+        )
+        return self
+
+    def toggle_touch_id_enrollment(self) -> Self:
+        """Toggle enroll touchId on iOS Simulator
+
+        Returns:
+            Union['WebDriver', 'HardwareActions']: Self instance
+        """
+        is_enrolled = self.execute_script('mobile: isBiometricEnrolled')
+        self.execute_script('mobile: enrollBiometric', {'isEnabled': not is_enrolled})
+        return self
+
+    def finger_print(self, finger_id: int) -> Self:
+        """Authenticate users by using their finger print scans on supported Android emulators.
+
+        Args:
+            finger_id: Finger prints stored in Android Keystore system (from 1 to 10)
+        """
+        ext_name = 'mobile: fingerprint'
+        args = {'fingerprintId': finger_id}
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name, args)
+        except UnknownMethodException:
+            self.mark_extension_absence(ext_name).execute(Command.FINGER_PRINT, args)
+        return self
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.LOCK, 'POST', '/session/$sessionId/appium/device/lock')
+        self.command_executor.add_command(Command.UNLOCK, 'POST', '/session/$sessionId/appium/device/unlock')
+        self.command_executor.add_command(Command.IS_LOCKED, 'POST', '/session/$sessionId/appium/device/is_locked')
+        self.command_executor.add_command(Command.SHAKE, 'POST', '/session/$sessionId/appium/device/shake')
+        self.command_executor.add_command(Command.TOUCH_ID, 'POST', '/session/$sessionId/appium/simulator/touch_id')
+        self.command_executor.add_command(
+            Command.TOGGLE_TOUCH_ID_ENROLLMENT,
+            'POST',
+            '/session/$sessionId/appium/simulator/toggle_touch_id_enrollment',
+        )
+        self.command_executor.add_command(
+            Command.FINGER_PRINT,
+            'POST',
+            '/session/$sessionId/appium/device/finger_print',
+        )

appium/webdriver/extensions/images_comparison.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import Any, Dict, Union
+
+from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class ImagesComparison(CanExecuteCommands):
+    def match_images_features(self, base64_image1: bytes, base64_image2: bytes, **opts: Any) -> Dict[str, Any]:
+        """Performs images matching by features.
+
+        Read
+        https://docs.opencv.org/3.0-beta/doc/py_tutorials/py_feature2d/py_matcher/py_matcher.html
+        for more details on this topic.
+        The method supports all image formats, which are supported by OpenCV itself.
+
+        Args:
+            base64_image1: base64-encoded content of the first image
+            base64_image2: base64-encoded content of the second image
+
+        Keyword Args:
+            visualize (bool): Set it to True in order to return the visualization of the matching operation.
+                matching visualization. False by default
+            detectorName (str): One of possible feature detector names:
+                'AKAZE', 'AGAST', 'BRISK', 'FAST', 'GFTT', 'KAZE', 'MSER', 'SIFT', 'ORB'
+                Some of these detectors are not enabled in the default OpenCV deployment.
+                'ORB' By default.
+            matchFunc (str): One of supported matching functions names:
+                'FlannBased', 'BruteForce', 'BruteForceL1', 'BruteForceHamming',
+                'BruteForceHammingLut', 'BruteForceSL2'
+                'BruteForce' by default
+            goodMatchesFactor (int): The maximum count of "good" matches (e. g. with minimal distances).
+                This count is unlimited by default.
+
+        Returns:
+            The dictionary containing the following entries:
+
+            visualization (bytes): base64-encoded content of PNG visualization of the current comparison
+                operation. This entry is only present if `visualize` option is enabled
+            count (int): The count of matched edges on both images.
+                The more matching edges there are no both images the more similar they are.
+            totalCount (int): The total count of matched edges on both images.
+                It is equal to `count` if `goodMatchesFactor` does not limit the matches,
+                otherwise it contains the total count of matches before `goodMatchesFactor` is
+                applied.
+            points1 (dict): The array of matching points on the first image. Each point is a dictionary
+                with 'x' and 'y' keys
+            rect1 (dict): The bounding rect for the `points1` array or a zero rect if not enough matching points
+                were found. The rect is represented by a dictionary with 'x', 'y', 'width' and 'height' keys
+            points2 (dict): The array of matching points on the second image. Each point is a dictionary
+                with 'x' and 'y' keys
+            rect2 (dict): The bounding rect for the `points2` array or a zero rect if not enough matching points
+                were found. The rect is represented by a dictionary with 'x', 'y', 'width' and 'height' keys
+        """
+        options = {'mode': 'matchFeatures', 'firstImage': base64_image1, 'secondImage': base64_image2, 'options': opts}
+        return self.execute(Command.COMPARE_IMAGES, options)['value']
+
+    def find_image_occurrence(
+        self, base64_full_image: bytes, base64_partial_image: bytes, **opts: Any
+    ) -> Dict[str, Union[bytes, Dict]]:
+        """Performs images matching by template to find possible occurrence of the partial image
+        in the full image.
+
+        Read
+        https://docs.opencv.org/2.4/doc/tutorials/imgproc/histograms/template_matching/template_matching.html
+        for more details on this topic.
+        The method supports all image formats, which are supported by OpenCV itself.
+
+        Args:
+            base64_full_image: base64-encoded content of the full image
+            base64_partial_image: base64-encoded content of the partial image
+
+        Keyword Args:
+            visualize (bool): Set it to True in order to return the visualization of the matching operation.
+                False by default
+
+        Returns:
+            The dictionary containing the following entries:
+                visualization (bytes): base64-encoded content of PNG visualization of the current comparison
+                    operation. This entry is only present if `visualize` option is enabled
+                rect (dict): The region of the partial image occurrence on the full image.
+                    The rect is represented by a dictionary with 'x', 'y', 'width' and 'height' keys
+        """
+        options = {
+            'mode': 'matchTemplate',
+            'firstImage': base64_full_image,
+            'secondImage': base64_partial_image,
+            'options': opts,
+        }
+        return self.execute(Command.COMPARE_IMAGES, options)['value']
+
+    def get_images_similarity(self, base64_image1: bytes, base64_image2: bytes, **opts: Any) -> Dict[str, Union[bytes, Dict]]:
+        """Performs images matching to calculate the similarity score between them.
+
+        The flow there is similar to the one used in
+        `find_image_occurrence`, but it is mandatory that both images are of equal resolution.
+        The method supports all image formats, which are supported by OpenCV itself.
+
+        Args:
+            base64_image1: base64-encoded content of the first image
+            base64_image2: base64-encoded content of the second image
+
+        Keyword Args:
+            visualize (boo): Set it to True in order to return the visualization of the matching operation.
+                False by default
+
+        Returns:
+            The dictionary containing the following entries:
+                visualization (bytes): base64-encoded content of PNG visualization of the current comparison
+                    operation. This entry is only present if `visualize` option is enabled
+                score (float): The similarity score as a float number in range [0.0, 1.0].
+                    1.0 is the highest score (means both images are totally equal).
+        """
+        options = {'mode': 'getSimilarity', 'firstImage': base64_image1, 'secondImage': base64_image2, 'options': opts}
+        return self.execute(Command.COMPARE_IMAGES, options)['value']
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.COMPARE_IMAGES, 'POST', '/session/$sessionId/appium/compare_images')