feat: Add Windows driver options (#732)

mykola-mokhnach · web-flow · commit d480ebaa1fcc · 2022-06-21T07:40:04.000+02:00
diff --git a/appium/options/common/app_option.py b/appium/options/common/app_option.py
@@ -26,7 +26,7 @@ class AppOption(SupportsCapabilities):
     @property
     def app(self) -> Optional[str]:
         """
-        :Returns: String representing app location.
+        String representing app location.
         """
         return self.get_capability(APP)
 
diff --git a/appium/options/common/auto_web_view_option.py b/appium/options/common/auto_web_view_option.py
@@ -26,7 +26,7 @@ class AutoWebViewOption(SupportsCapabilities):
     @property
     def auto_web_view(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should try to automatically switch
+        Whether the driver should try to automatically switch
         to a web view context after the session is started.
         """
         return self.get_capability(AUTO_WEB_VIEW)
diff --git a/appium/options/common/automation_name_option.py b/appium/options/common/automation_name_option.py
@@ -26,7 +26,7 @@ class AutomationNameOption(SupportsCapabilities):
     @property
     def automation_name(self) -> Optional[str]:
         """
-        :Returns: String representing the name of the automation engine name.
+        String representing the name of the automation engine name.
         """
         return self.get_capability(AUTOMATION_NAME)
 
diff --git a/appium/options/common/clear_system_files_option.py b/appium/options/common/clear_system_files_option.py
@@ -26,7 +26,7 @@ class ClearSystemFilesOption(SupportsCapabilities):
     @property
     def clear_system_files(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should delete generated files at the end of a session.
+        Whether the driver should delete generated files at the end of a session.
         """
         return self.get_capability(CLEAR_SYSTEM_FILES)
 
diff --git a/appium/options/common/device_name_option.py b/appium/options/common/device_name_option.py
@@ -26,7 +26,7 @@ class DeviceNameOption(SupportsCapabilities):
     @property
     def device_name(self) -> Optional[str]:
         """
-        :Returns: The name of the device.
+        The name of the device.
         """
         return self.get_capability(DEVICE_NAME)
 
diff --git a/appium/options/common/enable_performance_logging_option.py b/appium/options/common/enable_performance_logging_option.py
@@ -26,7 +26,7 @@ class EnablePerformanceLoggingOption(SupportsCapabilities):
     @property
     def enable_performance_logging(self) -> Optional[bool]:
         """
-        :Returns: Whether to enable additional performance logging.
+        Whether to enable additional performance logging.
         """
         return self.get_capability(ENABLE_PERFORMANCE_LOGGING)
 
diff --git a/appium/options/common/event_timings_option.py b/appium/options/common/event_timings_option.py
@@ -26,7 +26,7 @@ class EventTimingsOption(SupportsCapabilities):
     @property
     def event_timings(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should to report the timings
+        Whether the driver should to report the timings
         for various Appium-internal events.
         """
         return self.get_capability(EVENT_TIMINGS)
diff --git a/appium/options/common/full_reset_option.py b/appium/options/common/full_reset_option.py
@@ -26,7 +26,7 @@ class FullResetOption(SupportsCapabilities):
     @property
     def full_reset(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should perform a full reset.
+        Whether the driver should perform a full reset.
         """
         return self.get_capability(FULL_RESET)
 
diff --git a/appium/options/common/is_headless_option.py b/appium/options/common/is_headless_option.py
@@ -26,7 +26,7 @@ class IsHeadlessOption(SupportsCapabilities):
     @property
     def is_headless(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should start emulator/simulator in headless mode.
+        Whether the driver should start emulator/simulator in headless mode.
         """
         return self.get_capability(IS_HEADLESS)
 
diff --git a/appium/options/common/language_option.py b/appium/options/common/language_option.py
@@ -26,7 +26,7 @@ class LanguageOption(SupportsCapabilities):
     @property
     def language(self) -> Optional[str]:
         """
-        :Returns: Language abbreviation to use in a test session.
+        Language abbreviation to use in a test session.
         """
         return self.get_capability(LANGUAGE)
 
diff --git a/appium/options/common/locale_option.py b/appium/options/common/locale_option.py
@@ -26,7 +26,7 @@ class LocaleOption(SupportsCapabilities):
     @property
     def locale(self) -> Optional[str]:
         """
-        :Returns: Locale abbreviation to use in a test session.
+        Locale abbreviation to use in a test session.
         """
         return self.get_capability(LOCALE)
 
diff --git a/appium/options/common/new_command_timeout_option.py b/appium/options/common/new_command_timeout_option.py
@@ -27,7 +27,7 @@ class NewCommandTimeoutOption(SupportsCapabilities):
     @property
     def new_command_timeout(self) -> Optional[timedelta]:
         """
-        :Returns: The allowed time before seeing a new server command.
+        The allowed time before seeing a new server command.
         """
         value = self.get_capability(NEW_COMMAND_TIMEOUT)
         return None if value is None else timedelta(seconds=value)
diff --git a/appium/options/common/no_reset_option.py b/appium/options/common/no_reset_option.py
@@ -26,7 +26,7 @@ class NoResetOption(SupportsCapabilities):
     @property
     def full_reset(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should not perform a reset.
+        Whether the driver should not perform a reset.
         """
         return self.get_capability(NO_RESET)
 
diff --git a/appium/options/common/orientation_option.py b/appium/options/common/orientation_option.py
@@ -26,7 +26,7 @@ class OrientationOption(SupportsCapabilities):
     @property
     def orientation(self) -> Optional[str]:
         """
-        :Returns: The orientation of the device's screen.
+        The orientation of the device's screen.
         Usually this is either 'PORTRAIT' or 'LANDSCAPE'.
         """
         return self.get_capability(ORIENTATION)
diff --git a/appium/options/common/other_apps_option.py b/appium/options/common/other_apps_option.py
@@ -26,7 +26,7 @@ class OtherAppsOption(SupportsCapabilities):
     @property
     def other_apps(self) -> Optional[str]:
         """
-        :Returns: Locations of apps to install before running a test.
+        Locations of apps to install before running a test.
         """
         return self.get_capability(OTHER_APPS)
 
diff --git a/appium/options/common/postrun_option.py b/appium/options/common/postrun_option.py
@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Optional
+from typing import Dict, Optional
 
 from .supports_capabilities import SupportsCapabilities
 
@@ -24,15 +24,15 @@
 
 class PostrunOption(SupportsCapabilities):
     @property
-    def postrun(self) -> Optional[str]:
+    def postrun(self) -> Optional[Dict[str, str]]:
         """
-        :return: System script which is supposed to be executed upon
+        System script which is supposed to be executed upon
         driver session quit.
         """
         return self.get_capability(POSTRUN)
 
     @postrun.setter
-    def postrun(self, value: str) -> None:
+    def postrun(self, value: Dict[str, str]) -> None:
         """
         Set a system script to execute upon driver session quit.
         """
diff --git a/appium/options/common/prerun_option.py b/appium/options/common/prerun_option.py
@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from typing import Optional
+from typing import Dict, Optional
 
 from .supports_capabilities import SupportsCapabilities
 
@@ -24,15 +24,15 @@
 
 class PrerunOption(SupportsCapabilities):
     @property
-    def prerun(self) -> Optional[str]:
+    def prerun(self) -> Optional[Dict[str, str]]:
         """
-        :return: System script which is supposed to be executed before
+        System script which is supposed to be executed before
         a driver session is initialised.
         """
         return self.get_capability(PRERUN)
 
     @prerun.setter
-    def prerun(self, value: str) -> None:
+    def prerun(self, value: Dict[str, str]) -> None:
         """
         Set a system script which is supposed to be executed before
         a driver session is initialised.
diff --git a/appium/options/common/print_page_source_on_find_failure_option.py b/appium/options/common/print_page_source_on_find_failure_option.py
@@ -26,7 +26,7 @@ class PrintPageSourceOnFindFailureOption(SupportsCapabilities):
     @property
     def print_page_source_on_find_failure(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should print the page source to the log
+        Whether the driver should print the page source to the log
         if a find failure occurs.
         """
         return self.get_capability(PRINT_PAGE_SOURCE_ON_FIND_FAILURE)
diff --git a/appium/options/common/skip_log_capture_option.py b/appium/options/common/skip_log_capture_option.py
@@ -26,7 +26,7 @@ class SkipLogCaptureOption(SupportsCapabilities):
     @property
     def skip_log_capture(self) -> Optional[bool]:
         """
-        :Returns: Whether the driver should not record device logs.
+        Whether the driver should not record device logs.
         """
         return self.get_capability(SKIP_LOG_CAPTURE)
 
diff --git a/appium/options/common/udid_option.py b/appium/options/common/udid_option.py
@@ -26,7 +26,7 @@ class UdidOption(SupportsCapabilities):
     @property
     def udid(self) -> Optional[str]:
         """
-        :Returns: The unique identifier of the device under test.
+        The unique identifier of the device under test.
         """
         return self.get_capability(UDID)
 
diff --git a/appium/options/mac/mac2/arguments_option.py b/appium/options/mac/mac2/arguments_option.py
@@ -26,7 +26,7 @@ class ArgumentsOption(SupportsCapabilities):
     @property
     def arguments(self) -> Optional[List[str]]:
         """
-        :Returns: Array of application command line arguments.
+        Array of application command line arguments.
         """
         return self.get_capability(ARGUMENTS)
 
diff --git a/appium/options/mac/mac2/bootstrap_root_option.py b/appium/options/mac/mac2/bootstrap_root_option.py
@@ -26,7 +26,7 @@ class BootstrapRootOption(SupportsCapabilities):
     @property
     def bootstrap_root(self) -> Optional[str]:
         """
-        :Returns: The full path to WebDriverAgentMac root folder where Xcode project
+        The full path to WebDriverAgentMac root folder where Xcode project
         of the server sources lives.
         """
         return self.get_capability(BOOTSTRAP_ROOT)
diff --git a/appium/options/mac/mac2/bundle_id_option.py b/appium/options/mac/mac2/bundle_id_option.py
@@ -26,7 +26,7 @@ class BundleIdOption(SupportsCapabilities):
     @property
     def bundle_id(self) -> Optional[str]:
         """
-        :Returns: The bundle identifier of the application to automate.
+        The bundle identifier of the application to automate.
         """
         return self.get_capability(BUNDLE_ID)
 
diff --git a/appium/options/mac/mac2/environment_option.py b/appium/options/mac/mac2/environment_option.py
@@ -26,7 +26,7 @@ class EnvironmentOption(SupportsCapabilities):
     @property
     def environment(self) -> Optional[Dict[str, str]]:
         """
-        :Returns: Application environment variables mapping.
+        Application environment variables mapping.
         """
         return self.get_capability(ENVIRONMENT)
 
diff --git a/appium/options/mac/mac2/server_startup_timeout_option.py b/appium/options/mac/mac2/server_startup_timeout_option.py
@@ -27,7 +27,7 @@ class ServerStartupTimeoutOption(SupportsCapabilities):
     @property
     def server_startup_timeout(self) -> Optional[timedelta]:
         """
-        :Returns: Get the timeout to wait util the WebDriverAgentMac
+        Get the timeout to wait util the WebDriverAgentMac
         project is built and started.
         """
         value_ms = self.get_capability(SERVER_STARTUP_TIMEOUT)
diff --git a/appium/options/mac/mac2/show_server_logs_option.py b/appium/options/mac/mac2/show_server_logs_option.py
@@ -26,7 +26,7 @@ class ShowServerLogsOption(SupportsCapabilities):
     @property
     def show_server_logs(self) -> Optional[bool]:
         """
-        :Returns: Whether to show WDA server logs in the Appium log.
+        Whether to show WDA server logs in the Appium log.
         """
         return self.get_capability(SHOW_SERVER_LOGS)
 
diff --git a/appium/options/mac/mac2/skip_app_kill_option.py b/appium/options/mac/mac2/skip_app_kill_option.py
@@ -26,7 +26,7 @@ class SkipAppKillOption(SupportsCapabilities):
     @property
     def skip_app_kill(self) -> Optional[bool]:
         """
-        :Returns: Whether to skip the termination of the application under test.
+        Whether to skip the termination of the application under test.
         """
         return self.get_capability(SKIP_APP_KILL)
 
diff --git a/appium/options/mac/mac2/system_host_option.py b/appium/options/mac/mac2/system_host_option.py
@@ -26,7 +26,7 @@ class SystemHostOption(SupportsCapabilities):
     @property
     def system_host(self) -> Optional[str]:
         """
-        :Returns: The name of the host for the internal server to listen on.
+        The name of the host for the internal server to listen on.
         """
         return self.get_capability(SYSTEM_HOST)
 
diff --git a/appium/options/mac/mac2/system_port_option.py b/appium/options/mac/mac2/system_port_option.py
@@ -26,7 +26,7 @@ class SystemPortOption(SupportsCapabilities):
     @property
     def system_port(self) -> Optional[int]:
         """
-        :Returns: The number of the port for the internal server to listen on.
+        The number of the port for the internal server to listen on.
         """
         return self.get_capability(SYSTEM_PORT)
 
diff --git a/appium/options/mac/mac2/web_driver_agent_mac_url_option.py b/appium/options/mac/mac2/web_driver_agent_mac_url_option.py
@@ -26,7 +26,7 @@ class WebDriverAgentMacUrlOption(SupportsCapabilities):
     @property
     def web_driver_agent_mac_url(self) -> Optional[str]:
         """
-        :Returns: The URL Appium will connect to an existing WebDriverAgentMac instance.
+        The URL Appium will connect to an existing WebDriverAgentMac instance.
         """
         return self.get_capability(WEB_DRIVER_ARGENT_MAC_URL)
 
diff --git a/appium/options/windows/windows/app_top_level_window_option.py b/appium/options/windows/windows/app_top_level_window_option.py
@@ -0,0 +1,40 @@
+# 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 Optional
+
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+APP_TOP_LEVEL_WINDOW = 'appTopLevelWindow'
+
+
+class AppTopLevelWindowOption(SupportsCapabilities):
+    @property
+    def app_top_level_window(self) -> Optional[str]:
+        """
+        Hexadecimal handle of an existing application top level window to attach to.
+        """
+        return self.get_capability(APP_TOP_LEVEL_WINDOW)
+
+    @app_top_level_window.setter
+    def app_top_level_window(self, value: str) -> None:
+        """
+        Set the hexadecimal handle of an existing application top level
+        window to attach to, for example 0x12345 (should be of string type).
+        Either this capability or app one must be provided on session startup.
+        """
+        self.set_capability(APP_TOP_LEVEL_WINDOW, value)
diff --git a/appium/options/windows/windows/app_working_dir_option.py b/appium/options/windows/windows/app_working_dir_option.py
@@ -0,0 +1,40 @@
+# 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 Optional
+
+from appium.options.common.supports_capabilities import SupportsCapabilities
+
+APP_WORKING_DIR = 'appWorkingDir'
+
+
+class AppWorkingDirOption(SupportsCapabilities):
+    @property
+    def app_working_dir(self) -> Optional[str]:
+        """
+        Full path to the folder, which is going to be set as the working
+        dir for the application under test.
+        """
+        return self.get_capability(APP_WORKING_DIR)
+
+    @app_working_dir.setter
+    def app_working_dir(self, value: str) -> None:
+        """
+        Set the full path to the folder, which is going to be set as the working
+        dir for the application under test. This is only applicable for classic apps.
+        """
+        self.set_capability(APP_WORKING_DIR, value)
diff --git a/appium/options/windows/windows/base.py b/appium/options/windows/windows/base.py
diff --git a/appium/options/windows/windows/create_session_timeout_option.py b/appium/options/windows/windows/create_session_timeout_option.py
diff --git a/appium/options/windows/windows/expreimental_web_driver_option.py b/appium/options/windows/windows/expreimental_web_driver_option.py
diff --git a/appium/options/windows/windows/system_port_option.py b/appium/options/windows/windows/system_port_option.py
diff --git a/appium/options/windows/windows/wait_for_app_launch_option.py b/appium/options/windows/windows/wait_for_app_launch_option.py
