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

appium/webdriver/extensions/applications.py

@@ -0,0 +1,274 @@
+#!/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 selenium.common.exceptions import InvalidArgumentException, 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 Applications(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def background_app(self, seconds: int) -> Self:
+        """Puts the application in the background on the device for a certain duration.
+
+        Args:
+            seconds: the duration for the application to remain in the background.
+            Providing a negative value will continue immediately after putting the app
+            under test to the background.
+
+        Returns:
+            Union['WebDriver', 'Applications']: Self instance
+        """
+        ext_name = 'mobile: backgroundApp'
+        args = {'seconds': seconds}
+        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.BACKGROUND, args)
+        return self
+
+    def is_app_installed(self, bundle_id: str) -> bool:
+        """Checks whether the application specified by `bundle_id` is installed on the device.
+
+        Args:
+            bundle_id: the id of the application to query
+
+        Returns:
+            `True` if app is installed
+        """
+        ext_name = 'mobile: isAppInstalled'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    'bundleId': bundle_id,
+                    'appId': bundle_id,
+                },
+            )
+        except (UnknownMethodException, InvalidArgumentException):
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(
+                Command.IS_APP_INSTALLED,
+                {
+                    'bundleId': bundle_id,
+                },
+            )['value']
+
+    def install_app(self, app_path: str, **options: Any) -> Self:
+        """Install the application found at `app_path` on the device.
+
+        Args:
+            app_path: the local or remote path to the application to install
+
+        Keyword Args:
+            replace (bool): [Android only] whether to reinstall/upgrade the package if it is
+                already present on the device under test. True by default
+            timeout (int): [Android only] how much time to wait for the installation to complete.
+                60000ms by default.
+            allowTestPackages (bool): [Android only] whether to allow installation of packages marked
+                as test in the manifest. False by default
+            useSdcard (bool): [Android only] whether to use the SD card to install the app. False by default
+            grantPermissions (bool): [Android only] whether to automatically grant application permissions
+                on Android 6+ after the installation completes. False by default
+
+        Returns:
+            Union['WebDriver', 'Applications']: Self instance
+        """
+        ext_name = 'mobile: installApp'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(
+                'mobile: installApp',
+                {
+                    'app': app_path,
+                    'appPath': app_path,
+                    **(options or {}),
+                },
+            )
+        except (UnknownMethodException, InvalidArgumentException):
+            # TODO: Remove the fallback
+            data: Dict[str, Any] = {'appPath': app_path}
+            if options:
+                data.update({'options': options})
+            self.mark_extension_absence(ext_name).execute(Command.INSTALL_APP, data)
+        return self
+
+    def remove_app(self, app_id: str, **options: Any) -> Self:
+        """Remove the specified application from the device.
+
+        Args:
+            app_id: the application id to be removed
+
+        Keyword Args:
+            keepData (bool): [Android only] whether to keep application data and caches after it is uninstalled.
+                False by default
+            timeout (int): [Android only] how much time to wait for the uninstall to complete.
+                20000ms by default.
+
+        Returns:
+            Union['WebDriver', 'Applications']: Self instance
+        """
+        ext_name = 'mobile: removeApp'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    'appId': app_id,
+                    'bundleId': app_id,
+                    **(options or {}),
+                },
+            )
+        except (UnknownMethodException, InvalidArgumentException):
+            # TODO: Remove the fallback
+            data: Dict[str, Any] = {'appId': app_id}
+            if options:
+                data.update({'options': options})
+            self.mark_extension_absence(ext_name).execute(Command.REMOVE_APP, data)
+        return self
+
+    def terminate_app(self, app_id: str, **options: Any) -> bool:
+        """Terminates the application if it is running.
+
+        Args:
+            app_id: the application id to be terminates
+
+        Keyword Args:
+            `timeout` (int): [Android only] how much time to wait for the uninstall to complete.
+                500ms by default.
+
+        Returns:
+            True if the app has been successfully terminated
+        """
+        ext_name = 'mobile: terminateApp'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    'appId': app_id,
+                    'bundleId': app_id,
+                    **(options or {}),
+                },
+            )
+        except (UnknownMethodException, InvalidArgumentException):
+            # TODO: Remove the fallback
+            data: Dict[str, Any] = {'appId': app_id}
+            if options:
+                data.update({'options': options})
+            return self.mark_extension_absence(ext_name).execute(Command.TERMINATE_APP, data)['value']
+
+    def activate_app(self, app_id: str) -> Self:
+        """Activates the application if it is not running
+        or is running in the background.
+
+        Args:
+            app_id: the application id to be activated
+
+        Returns:
+            Union['WebDriver', 'Applications']: Self instance
+        """
+        ext_name = 'mobile: activateApp'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    'appId': app_id,
+                    'bundleId': app_id,
+                },
+            )
+        except (UnknownMethodException, InvalidArgumentException):
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.ACTIVATE_APP, {'appId': app_id})
+        return self
+
+    def query_app_state(self, app_id: str) -> int:
+        """Queries the state of the application.
+
+        Args:
+            app_id: the application id to be queried
+
+        Returns:
+            One of possible application state constants. See ApplicationState
+            class for more details.
+        """
+        ext_name = 'mobile: queryAppState'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    'appId': app_id,
+                    'bundleId': app_id,
+                },
+            )
+        except (UnknownMethodException, InvalidArgumentException):
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(
+                Command.QUERY_APP_STATE,
+                {
+                    'appId': app_id,
+                },
+            )['value']
+
+    def app_strings(self, language: Union[str, None] = None, string_file: Union[str, None] = None) -> Dict[str, str]:
+        """Returns the application strings from the device for the specified
+        language.
+
+        Args:
+            language: strings language code
+            string_file: the name of the string file to query. Only relevant for XCUITest driver
+
+        Returns:
+            The key is string id and the value is the content.
+        """
+        ext_name = 'mobile: getAppStrings'
+        data = {}
+        if language is not None:
+            data['language'] = language
+        if string_file is not None:
+            data['stringFile'] = string_file
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name, data)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.GET_APP_STRINGS, data)['value']
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.BACKGROUND, 'POST', '/session/$sessionId/appium/app/background')
+        self.command_executor.add_command(
+            Command.IS_APP_INSTALLED,
+            'POST',
+            '/session/$sessionId/appium/device/app_installed',
+        )
+        self.command_executor.add_command(Command.INSTALL_APP, 'POST', '/session/$sessionId/appium/device/install_app')
+        self.command_executor.add_command(Command.REMOVE_APP, 'POST', '/session/$sessionId/appium/device/remove_app')
+        self.command_executor.add_command(
+            Command.TERMINATE_APP,
+            'POST',
+            '/session/$sessionId/appium/device/terminate_app',
+        )
+        self.command_executor.add_command(
+            Command.ACTIVATE_APP,
+            'POST',
+            '/session/$sessionId/appium/device/activate_app',
+        )
+        self.command_executor.add_command(
+            Command.QUERY_APP_STATE,
+            'POST',
+            '/session/$sessionId/appium/device/app_state',
+        )
+        self.command_executor.add_command(Command.GET_APP_STRINGS, 'POST', '/session/$sessionId/appium/app/strings')

appium/webdriver/extensions/clipboard.py

@@ -0,0 +1,107 @@
+#!/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 base64
+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 appium.webdriver.clipboard_content_type import ClipboardContentType
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class Clipboard(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def set_clipboard(
+        self, content: bytes, content_type: str = ClipboardContentType.PLAINTEXT, label: Optional[str] = None
+    ) -> Self:
+        """Set the content of the system clipboard
+
+        Args:
+            content: The content to be set as bytearray string
+            content_type: One of ClipboardContentType items. Only ClipboardContentType.PLAINTEXT
+                is supported on Android
+            label: label argument, which only works for Android
+
+        Returns:
+            Union['WebDriver', 'Clipboard']: Self instance
+        """
+        ext_name = 'mobile: setClipboard'
+        options = {
+            'content': base64.b64encode(content).decode('UTF-8'),
+            'contentType': content_type,
+        }
+        if label:
+            options['label'] = label
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name, options)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.SET_CLIPBOARD, options)
+        return self
+
+    def set_clipboard_text(self, text: str, label: Optional[str] = None) -> Self:
+        """Copies the given text to the system clipboard
+
+        Args:
+            text: The text to be set
+            label:label argument, which only works for Android
+
+        Returns:
+            Union['WebDriver', 'Clipboard']: Self instance
+        """
+        return self.set_clipboard(bytes(str(text), 'UTF-8'), ClipboardContentType.PLAINTEXT, label)
+
+    def get_clipboard(self, content_type: str = ClipboardContentType.PLAINTEXT) -> bytes:
+        """Receives the content of the system clipboard
+
+        Args:
+            content_type: One of ClipboardContentType items. Only ClipboardContentType.PLAINTEXT
+                is supported on Android
+
+        Returns:
+            Clipboard content as bytearray. Or empty bytes if the clipboard is empty
+        """
+        ext_name = 'mobile: getClipboard'
+        options = {'contentType': content_type}
+        try:
+            base64_str = self.assert_extension_exists(ext_name).execute_script(ext_name, options)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            base64_str = self.mark_extension_absence(ext_name).execute(Command.GET_CLIPBOARD, options)['value']
+        return base64.b64decode(base64_str)
+
+    def get_clipboard_text(self) -> str:
+        """Receives the text of the system clipboard
+
+        Returns:
+            The actual clipboard text or an empty string if the clipboard is empty
+        """
+        return self.get_clipboard(ClipboardContentType.PLAINTEXT).decode('UTF-8')
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(
+            Command.SET_CLIPBOARD,
+            'POST',
+            '/session/$sessionId/appium/device/set_clipboard',
+        )
+        self.command_executor.add_command(
+            Command.GET_CLIPBOARD,
+            'POST',
+            '/session/$sessionId/appium/device/get_clipboard',
+        )

appium/webdriver/extensions/context.py

@@ -0,0 +1,63 @@
+#!/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 List
+
+from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class Context(CanExecuteCommands):
+    @property
+    def contexts(self) -> List[str]:
+        """Returns the contexts within the current session.
+
+        Usage:
+            driver.contexts
+
+        Return:
+            :obj:`list` of :obj:`str`: The contexts within the current session
+
+        """
+        return self.execute(Command.CONTEXTS)['value']
+
+    @property
+    def current_context(self) -> str:
+        """Returns the current context of the current session.
+
+        Usage:
+            driver.current_context
+
+        Return:
+            str: The context of the current session
+        """
+        return self.execute(Command.GET_CURRENT_CONTEXT)['value']
+
+    @property
+    def context(self) -> str:
+        """Returns the current context of the current session.
+
+        Usage:
+            driver.context
+
+        Return:
+            str: The context of the current session
+        """
+        return self.current_context
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.CONTEXTS, 'GET', '/session/$sessionId/contexts')
+        self.command_executor.add_command(Command.GET_CURRENT_CONTEXT, 'GET', '/session/$sessionId/context')
+        self.command_executor.add_command(Command.SWITCH_TO_CONTEXT, 'POST', '/session/$sessionId/context')

appium/webdriver/extensions/device_time.py

@@ -0,0 +1,75 @@
+#!/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 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 DeviceTime(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    @property
+    def device_time(self) -> str:
+        """Returns the date and time from the device.
+
+        Return:
+            str: The date and time
+        """
+        ext_name = 'mobile: getDeviceTime'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.GET_DEVICE_TIME_GET, {})['value']
+
+    def get_device_time(self, format: Optional[str] = None) -> str:
+        """Returns the date and time from the device.
+
+        Args:
+            format:  The set of format specifiers. Read https://momentjs.com/docs/
+                to get the full list of supported datetime format specifiers.
+                If unset, return :func:`.device_time` as default format is `YYYY-MM-DDTHH:mm:ssZ`,
+                which complies to ISO-8601
+
+        Usage:
+            | self.driver.get_device_time()
+            | self.driver.get_device_time("YYYY-MM-DD")
+
+        Return:
+            str: The date and time
+        """
+        ext_name = 'mobile: getDeviceTime'
+        if format is None:
+            return self.device_time
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name, {'format': format})
+        except UnknownMethodException:
+            return self.mark_extension_absence(ext_name).execute(Command.GET_DEVICE_TIME_POST, {'format': format})['value']
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(
+            Command.GET_DEVICE_TIME_GET,
+            'GET',
+            '/session/$sessionId/appium/device/system_time',
+        )
+        self.command_executor.add_command(
+            Command.GET_DEVICE_TIME_POST,
+            'POST',
+            '/session/$sessionId/appium/device/system_time',
+        )

appium/webdriver/extensions/execute_driver.py

@@ -0,0 +1,60 @@
+#!/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, Optional, Union
+
+from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class ExecuteDriver(CanExecuteCommands):
+    # TODO Inner class case
+    def execute_driver(self, script: str, script_type: str = 'webdriverio', timeout_ms: Optional[int] = None) -> Any:
+        """Run a set of script against the current session, allowing execution of many commands in one Appium request.
+        Please read http://appium.io/docs/en/commands/session/execute-driver for more details about the acceptable
+        scripts and the output format.
+
+        Args:
+            script: The string consisting of the script itself
+            script_type: The name of the script type. Defaults to 'webdriverio'.
+            timeout_ms: The number of `ms` Appium should wait for the script to finish before
+             killing it due to timeout_ms.
+
+        Usage:
+            | self.driver.execute_driver(script='return [];')
+            | self.driver.execute_driver(script='return [];', script_type='webdriverio')
+            | self.driver.execute_driver(script='return [];', script_type='webdriverio', timeout_ms=10000)
+
+        Returns:
+            ExecuteDriver.Result: The result of the script. It has 'result' and 'logs' keys.
+
+        Raises:
+            WebDriverException: If something error happens in the script. The message has the original error message.
+        """
+
+        class Result:
+            def __init__(self, res: Dict):
+                self.result = res['result']
+                self.logs = res['logs']
+
+        option: Dict[str, Union[str, int]] = {'script': script, 'type': script_type}
+        if timeout_ms is not None:
+            option['timeout'] = timeout_ms
+
+        response = self.execute(Command.EXECUTE_DRIVER, option)['value']
+        return Result(response)
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.EXECUTE_DRIVER, 'POST', '/session/$sessionId/appium/execute_driver')

appium/webdriver/extensions/execute_mobile_command.py

@@ -0,0 +1,62 @@
+#!/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
+
+from typing_extensions import Self
+
+from appium.protocols.webdriver.can_execute_scripts import CanExecuteScripts
+
+
+class ExecuteMobileCommand(CanExecuteScripts):
+    def press_button(self, button_name: str) -> Self:
+        """Sends a physical button name to the device to simulate the user pressing.
+
+        iOS only.
+        Possible button names can be found in
+        https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentLib/Categories/XCUIDevice%2BFBHelpers.h
+
+        Args:
+            button_name: the button name to be sent to the device
+
+        Returns:
+            Union['WebDriver', 'ExecuteMobileCommand']: Self instance
+
+        """
+        data = {'name': button_name}
+        self.execute_script('mobile: pressButton', data)
+        return self
+
+    @property
+    def battery_info(self) -> Dict[str, Any]:
+        """Retrieves battery information for the device under test.
+
+        Returns:
+            `dict`: containing the following entries
+                level: Battery level in range [0.0, 1.0], where 1.0 means 100% charge.
+                    Any value lower than 0 means the level cannot be retrieved
+                state: Platform-dependent battery state value.
+                    On iOS (XCUITest):
+                        1: Unplugged
+                        2: Charging
+                        3: Full
+                        Any other value means the state cannot be retrieved
+                    On Android (UIAutomator2):
+                        2: Charging
+                        3: Discharging
+                        4: Not charging
+                        5: Full
+                        Any other value means the state cannot be retrieved
+        """
+        return self.execute_script('mobile: batteryInfo')

appium/webdriver/extensions/flutter_integration/__init__.py

@@ -0,0 +1,13 @@
+#!/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.